Elasticsearch MCP Server

Elasticsearch MCP 服务

本项目实现了一个适用于 Elasticsearch 的 MCP（Model Context Protocol）服务，提供用于与 Elasticsearch 集群交互的工具和资源。

功能

工具

• list_indices：列出 Elasticsearch 集群中的所有索引
• get_mappings：获取指定索引的映射
• search：使用提供的查询 DSL 执行 Elasticsearch 搜索
• search_with_query_string：使用简单查询字符串执行搜索
• get_index_stats：获取指定索引的统计信息

资源

• elasticsearch://indices：列出所有 Elasticsearch 索引
• elasticsearch://index/{index_name}：获取指定索引的详细信息
• elasticsearch://mapping/{index_name}：获取指定索引的映射信息

前置条件

• Python 3.7+
• Elasticsearch Python 客户端
• MCP SDK
• Elasticsearch 集群凭据（Cloud ID 和 API Key）

设置

1. 克隆代码库：

   git clone https://github.com/yourusername/elasticsearch-mcp-server.git
   cd elasticsearch-mcp-server
   

2. 安装所需依赖：

   pip install -r requirements.txt
   

3. 设置环境变量：

   • 复制示例环境文件：cp .env.example .env
   • 编辑 .env 文件并添加 Elasticsearch 凭据

   或直接在 shell 中设置：

   export ES_CLOUD_ID=your_elasticsearch_cloud_id
   export ES_API_KEY=your_elasticsearch_api_key
   

为 Claude 配置 MCP 服务

configure_mcp_server.py 脚本可帮助你在 Claude 的 MCP 设置文件中配置 Elasticsearch MCP 服务。这样，Claude 就可以通过 MCP 服务连接到你的 Elasticsearch 集群。

python configure_mcp_server.py your_cloud_id your_api_key

此脚本会：

1. 将 Elasticsearch Cloud ID 和 API Key 作为命令行参数
2. 定位或创建 Claude MCP 设置文件
3. 添加或更新 Elasticsearch MCP 服务配置
4. 设置服务连接到 Elasticsearch 集群所需的环境变量

运行此脚本后，重启 VS Code 以应用更改。随后，Claude 就能够使用 Elasticsearch MCP 服务与 Elasticsearch 集群交互。

测试 MCP 资源

选项 1：使用测试脚本

我们提供了一个测试脚本，它会启动 MCP 服务并提供测试说明：

# Make the script executable if needed
chmod +x test_es_mcp.sh

# Run the test script
ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key ./test_es_mcp.sh

脚本会：

1. 在后台启动 MCP 服务
2. 提供测试资源的说明
3. 保持服务运行，直到你按下 Ctrl+C

选项 2：手动测试

1. 启动 MCP 服务：

   ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key python es_mcp_server.py
   

2. 在 Claude 中，使用 access_mcp_resource 工具访问资源：

   a. 列出所有索引：

   <access_mcp_resource>
   <server_name>elasticsearch-mcp-server</server_name>
   <uri>elasticsearch://indices</uri>
   </access_mcp_resource>
   

   b. 获取指定索引的信息：

   <access_mcp_resource>
   <server_name>elasticsearch-mcp-server</server_name>
   <uri>elasticsearch://index/your_index_name</uri>
   </access_mcp_resource>
   

   c. 获取指定索引的映射：

   <access_mcp_resource>
   <server_name>elasticsearch-mcp-server</server_name>
   <uri>elasticsearch://mapping/your_index_name</uri>
   </access_mcp_resource>
   

选项 3：使用 Python 测试脚本

我们还提供了一个 Python 测试脚本，演示如何访问这些资源：

ES_CLOUD_ID=your_cloud_id ES_API_KEY=your_api_key python test_es_resources.py

资源详情

elasticsearch://indices

返回 Elasticsearch 集群中所有索引的 JSON 数组，包括：

• 索引名称
• 健康状态
• 状态
• 文档数
• 大小

elasticsearch://index/{index_name}

返回指定索引的详细信息，包括：

• 索引名称
• 设置
• 统计信息（文档数、字节和 MB 为单位的大小）

elasticsearch://mapping/{index_name}

返回指定索引的映射信息，包括：

• 完整的映射定义
• 字段数
• 字段类型分布

错误处理

所有资源都包含适当的错误处理和验证：

• 如果索引不存在，资源会返回相应的错误消息
• 如果连接 Elasticsearch 时出现问题，资源会返回错误消息
• 所有异常都会被捕获，并以易读的错误消息形式返回

贡献

欢迎贡献！你可以通过以下方式参与：

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 提交更改：git commit -am 'Add some feature'
4. 将分支推送到远程：git push origin feature/your-feature-name
5. 提交拉取请求

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。