Elasticsearch MCP Server

Elasticsearch MCP 服务器

该存储库包含用于研究和评估的实验性功能，尚不适用于生产。

使用模型上下文协议 (MCP) 直接从任何 MCP 客户端（如 Claude Desktop）连接到您的 Elasticsearch 数据。

该服务器使用模型上下文协议 (MCP) 将代理连接到您的 Elasticsearch 数据。它允许您通过自然语言对话与您的 Elasticsearch 索引进行交互。

可用工具

• list_indices ：列出所有可用的 Elasticsearch 索引
• get_mappings ：获取特定 Elasticsearch 索引的字段映射
• search ：使用提供的查询 DSL 执行 Elasticsearch 搜索
• get_shards ：获取所有或特定索引的分片信息

先决条件

• Elasticsearch 实例
• Elasticsearch 身份验证凭据（API 密钥或用户名/密码）
• MCP 客户端（例如 Claude Desktop）

演示

https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c

安装和设置

使用已发布的 NPM 包

[!TIP] 使用 Elasticsearch MCP Server 最简单的方法是通过已发布的 npm 包。

1. 配置 MCP 客户端
   • 打开您的 MCP 客户端。查看MCP 客户端列表，这里我们正在配置 Claude 桌面。
   • 前往**“设置”>“开发者”>“MCP 服务器”**
   • 单击Edit Config并添加具有以下配置的新 MCP 服务器：
   { "mcpServers": { "elasticsearch-mcp-server": { "command": "npx", "args": [ "-y", "@elastic/mcp-server-elasticsearch" ], "env": { "ES_URL": "your-elasticsearch-url", "ES_API_KEY": "your-api-key" } } } }
2. 开始对话
   • 在 MCP 客户端中打开新对话
   • MCP 服务器应该会自动连接
   • 您现在可以询问有关 Elasticsearch 数据的问题

配置选项

Elasticsearch MCP 服务器支持配置选项来连接到您的 Elasticsearch：

[!NOTE] 您必须提供 API 密钥或用户名和密码进行身份验证。

本地开发

[!NOTE] 如果您想修改或扩展 MCP 服务器，请按照这些本地开发步骤操作。

1. 使用正确的 Node.js 版本
   nvm use
2. 安装依赖项
   npm install
3. 构建项目
   npm run build
4. 在 Claude 桌面应用程序中本地运行
   • 打开Claude 桌面应用程序
   • 前往**“设置”>“开发者”>“MCP 服务器”**
   • 单击Edit Config并添加具有以下配置的新 MCP 服务器：
   { "mcpServers": { "elasticsearch-mcp-server-local": { "command": "node", "args": [ "/path/to/your/project/dist/index.js" ], "env": { "ES_URL": "your-elasticsearch-url", "ES_API_KEY": "your-api-key" } } } }
5. 使用 MCP Inspector 进行调试
   ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector
   这将启动 MCP 检查器，允许您调试和分析请求。您应该看到：
   Starting MCP inspector... Proxy server listening on port 3000 🔍 MCP Inspector is up and running at http://localhost:5173 🚀

贡献

我们欢迎社区的贡献！有关如何贡献的详细信息，请参阅贡献指南。

示例问题

[!TIP] 您可以使用 MCP 客户端尝试以下一些自然语言查询。

• “我的 Elasticsearch 集群中有哪些索引？”
• “显示‘产品’索引的字段映射。”
• “查找上个月所有超过 500 美元的订单。”
• “哪些产品获得最多五星评价？”

工作原理

1. MCP 客户端分析您的请求并确定需要哪些 Elasticsearch 操作。
2. MCP 服务器执行这些操作（列出索引、获取映射、执行搜索）。
3. MCP 客户端处理结果并以用户友好的格式呈现。

安全最佳实践

避免使用集群管理员权限。请创建具有有限范围的专用 API 密钥，并在索引级别应用细粒度的访问控制，以防止未经授权的数据访问。

您可以创建具有最小权限的专用 Elasticsearch API 密钥来控制对您的数据的访问：

执照

该项目采用 Apache License 2.0 许可。

故障排除

• 确保您的 MCP 配置正确。
• 验证您的 Elasticsearch URL 是否可以从您的机器访问。
• 检查您的身份验证凭据（API 密钥或用户名/密码）是否具有必要的权限。
• 如果使用带有自定义 CA 的 SSL/TLS，请验证证书路径是否正确以及文件是否可读。
• 查看终端输出中的错误消息。

如果您遇到问题，请随时在 GitHub 存储库上打开问题。