Elasticsearch MCP

🚀 Octodet Elasticsearch MCP Server

Octodet Elasticsearch MCP Server 是一個用於 Elasticsearch 操作的模型上下文協議（MCP）服務器。它通過標準化的模型上下文協議，提供了一套全面的工具，用於與 Elasticsearch 集群進行交互。藉助該服務器，由大語言模型（LLM）驅動的應用程序能夠對 Elasticsearch 數據進行搜索、更新和管理。

🚀 快速開始

本服務器提供了多種使用方式，你可以根據需求選擇合適的安裝和集成方法。

✨ 主要特性

• 完整的 Elasticsearch 操作：支持對文檔和索引進行完整的 CRUD 操作。
• 批量操作：可在單個 API 調用中處理多個操作。
• 基於查詢的更新/刪除：根據查詢條件修改或刪除文檔。
• 集群管理：監控集群的健康狀態、分片信息和模板。
• 高級搜索：全面支持 Elasticsearch DSL 查詢，並提供高亮顯示功能。

📦 安裝指南

作為 NPM 包安裝

你可以選擇全局安裝該包：

npm install -g @octodet/elasticsearch-mcp

或者直接使用 npx 運行：

npx @octodet/elasticsearch-mcp

從源代碼安裝

1. 克隆此倉庫。
2. 安裝依賴：

npm install

3. 構建服務器：

npm run build

💻 使用示例

與 MCP 客戶端集成

VS Code 集成

在你的 VS Code 設置文件 settings.json 中添加以下配置，以集成 VS Code MCP 擴展：

"mcp.servers": {
  "elasticsearch": {
    "command": "npx",
    "args": [
      "-y", "@octodet/elasticsearch-mcp"
    ],
    "env": {
      "ES_URL": "http://localhost:9200",
      "ES_API_KEY": "your_api_key",
      "ES_VERSION": "8"
    }
  }
}

Claude Desktop 集成

在你的 Claude Desktop 配置文件中進行如下配置：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@octodet/elasticsearch-mcp"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

本地開發配置

如果你在本地開發 MCP 服務器，可以配置客戶端使用本地構建的版本：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

配置說明

服務器使用以下環境變量進行配置：

工具使用示例

服務器提供了 16 個用於 Elasticsearch 操作的 MCP 工具，每個工具都有詳細的參數說明和使用示例：

1. 列出索引

列出所有可用的 Elasticsearch 索引，並提供詳細信息。 參數：

• indexPattern（可選，字符串）：用於過濾索引的模式（例如，"logs-"、"my-index-"）

示例：

{
  "indexPattern": "logs-*"
}

2. 獲取映射

獲取特定 Elasticsearch 索引的字段映射。 參數：

• index（必需，字符串）：要獲取映射的索引名稱

示例：

{
  "index": "my-index"
}

3. 搜索

使用提供的查詢 DSL 進行 Elasticsearch 搜索，並支持高亮顯示。 參數：

• index（必需，字符串）：要搜索的索引（支持逗號分隔的多個索引）
• queryBody（必需，對象）：Elasticsearch 查詢 DSL 主體
• highlight（可選，布爾值）：是否啟用搜索結果高亮顯示（默認：true）

示例：

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "search term"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. 獲取集群健康狀態

獲取 Elasticsearch 集群的健康信息。 參數：

• 無

示例：

{}

5. 獲取分片信息

獲取所有或特定索引的分片信息。 參數：

• index（可選，字符串）：要獲取分片信息的特定索引。如果省略，則返回所有索引的分片信息

示例：

{
  "index": "my-index"
}

6. 添加文檔

向特定的 Elasticsearch 索引中添加新文檔。 參數：

• index（必需，字符串）：要添加文檔的索引名稱
• document（必需，對象）：要添加的文檔內容
• id（可選，字符串）：文檔 ID。如果省略，Elasticsearch 將自動生成一個

示例：

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "My Document",
    "content": "Document content here",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "draft"]
  }
}

7. 更新文檔

更新特定 Elasticsearch 索引中的現有文檔。 參數：

• index（必需，字符串）：包含要更新文檔的索引名稱
• id（必需，字符串）：要更新的文檔 ID
• document（必需，對象）：包含要更新字段的部分文檔

示例：

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Updated Document Title",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. 刪除文檔

從特定的 Elasticsearch 索引中刪除文檔。 參數：

• index（必需，字符串）：包含要刪除文檔的索引名稱
• id（必需，字符串）：要刪除的文檔 ID

示例：

{
  "index": "my-index",
  "id": "doc1"
}

9. 按查詢更新

根據查詢條件更新 Elasticsearch 索引中的文檔。 參數：

• index（必需，字符串）：要更新文檔的索引名稱
• query（必需，對象）：用於匹配要更新文檔的 Elasticsearch 查詢
• script（必需，對象）：用於更新匹配文檔的腳本
• conflicts（可選，字符串）：如何處理版本衝突（"abort" 或 "proceed"，默認："abort"）
• refresh（可選，布爾值）：操作完成後是否刷新索引（默認：false）

示例：

{
  "index": "my-index",
  "query": {
    "term": {
      "status": "active"
    }
  },
  "script": {
    "source": "ctx._source.status = params.newStatus; ctx._source.updated_at = params.timestamp",
    "params": {
      "newStatus": "inactive",
      "timestamp": "2025-06-23T10:30:00Z"
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

10. 按查詢刪除

根據查詢條件刪除 Elasticsearch 索引中的文檔。 參數：

• index（必需，字符串）：要刪除文檔的索引名稱
• query（必需，對象）：用於匹配要刪除文檔的 Elasticsearch 查詢
• conflicts（可選，字符串）：如何處理版本衝突（"abort" 或 "proceed"，默認："abort"）
• refresh（可選，布爾值）：操作完成後是否刷新索引（默認：false）

示例：

{
  "index": "my-index",
  "query": {
    "range": {
      "created_date": {
        "lt": "2025-01-01"
      }
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

11. 批量操作

在單個 API 調用中執行多個文檔操作，以提高性能。 參數：

• operations（必需，數組）：操作對象數組，每個對象包含：
  • action（必需，字符串）：操作類型（"index"、"create"、"update" 或 "delete"）
  • index（必需，字符串）：操作的索引名稱
  • id（可選，字符串）：文檔 ID（更新/刪除操作必需，索引/創建操作可選）
  • document（條件性，對象）：文檔內容（索引/創建/更新操作必需）

示例：

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Content here" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Updated Title" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. 創建索引

創建一個新的 Elasticsearch 索引，並可選擇設置索引的參數和映射。 參數：

• index（必需，字符串）：要創建的索引名稱
• settings（可選，對象）：索引設置，如分片數、副本數等
• mappings（可選，對象）：字段映射，定義文檔的索引方式

示例：

{
  "index": "new-index",
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "standard",
          "stopwords": "_english_"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "custom_analyzer"
      },
      "created": {
        "type": "date",
        "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
      },
      "tags": {
        "type": "keyword"
      }
    }
  }
}

13. 刪除索引

永久刪除一個 Elasticsearch 索引。 參數：

• index（必需，字符串）：要刪除的索引名稱

示例：

{
  "index": "my-index"
}

14. 統計文檔數量

統計索引中的文檔數量，可選擇根據查詢條件進行過濾。 參數：

• index（必需，字符串）：要統計文檔數量的索引名稱
• query（可選，對象）：用於過濾要統計文檔的 Elasticsearch 查詢

示例：

{
  "index": "my-index",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "active" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. 獲取模板

從 Elasticsearch 獲取索引模板。 參數：

• name（可選，字符串）：要檢索的特定模板名稱。如果省略，則返回所有模板

示例：

{
  "name": "logs-template"
}

16. 獲取別名

從 Elasticsearch 獲取索引別名。 參數：

• name（可選，字符串）：要檢索的特定別名名稱。如果省略，則返回所有別名

示例：

{
  "name": "logs-alias"
}

🔧 技術細節

開發模式運行

在開發過程中，可以使用以下命令以監聽模式運行服務器：

npm run dev

協議實現

本服務器實現了 Model Context Protocol，以實現大語言模型（LLM）客戶端與 Elasticsearch 之間的標準化通信。通過該協議，MCP 客戶端可以調用服務器提供的工具，執行各種 Elasticsearch 操作。

添加新工具

若要向服務器添加新工具，可按以下步驟操作：

1. 在 src/index.ts 中使用 MCP 服務器的工具註冊格式定義新工具。
2. 在 src/utils/elasticsearchService.ts 中實現新工具的必要功能。
3. 更新本 README 文件，記錄新工具的使用方法。

📚 詳細文檔

其他 MCP 客戶端支持

本服務器可以與任何兼容 MCP 的客戶端配合使用，包括：

• 通過 MCP 插件使用的 OpenAI ChatGPT
• Anthropic 的 Claude Desktop
• VS Code 中的 Claude
• 使用 MCP SDK 的自定義應用程序

編程式使用

你還可以在 Node.js 應用程序中通過編程方式使用本服務器：

import { createOctodetElasticsearchMcpServer } from "@octodet/elasticsearch-mcp";
import { CustomTransport } from "@modelcontextprotocol/sdk/server";

// Configure the Elasticsearch connection
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Create and start the server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connect to your custom transport
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP server started");
}

startServer().catch(console.error);

📄 許可證

本項目採用 MIT 許可證，詳情請查看 LICENSE 文件。