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 文件。