MCP Es

🚀 Elasticsearch MCP Server

Elasticsearch MCP Server允许你通过Model Context Protocol (MCP) 直接从任何MCP客户端（如Claude Desktop）连接到你的Elasticsearch数据。它能让你通过自然语言对话与Elasticsearch索引进行交互，不过此仓库包含的是用于研究和评估的实验性功能，尚未达到生产就绪状态。

🚀 快速开始

前提条件

• 一个Elasticsearch实例。
• Elasticsearch认证凭证（API密钥或用户名/密码）。
• MCP客户端（例如Claude Desktop）。

安装与设置

使用已发布的NPM包

💡 使用建议 使用Elasticsearch MCP Server最简单的方法是通过已发布的npm包。

1. 配置MCP客户端

   • 打开你的MCP客户端。查看MCP客户端列表，这里我们以配置Claude Desktop为例。
   • 转到设置 > 开发者 > MCP服务器。
   • 点击编辑配置，并添加一个新的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数据的问题。

本地开发

⚠️ 重要提示 如果你想修改或扩展MCP服务器，请按照以下本地开发步骤操作。

1. 使用正确的Node.js版本

   nvm use
   

2. 安装依赖项

   npm install
   

3. 构建项目

   npm run build
   

4. 在Claude Desktop应用中本地运行

   • 打开Claude Desktop应用。
   • 转到设置 > 开发者 > MCP服务器。
   • 点击编辑配置，并添加一个新的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检查器进行调试

   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 🚀
   

✨ 主要特性

可用工具

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

示例问题

💡 使用建议 以下是一些你可以在MCP客户端中尝试的自然语言查询。

• "What indices do I have in my Elasticsearch cluster?"（我的Elasticsearch集群中有哪些索引？）
• "Show me the field mappings for the 'products' index."（给我展示'products'索引的字段映射。）
• "Find all orders over $500 from last month."（查找上个月所有超过500美元的订单。）
• "Which products received the most 5-star reviews?"（哪些产品获得了最多的五星评价？）

工作原理

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

📦 安装指南

配置选项

Elasticsearch MCP Server支持配置选项以连接到你的Elasticsearch：

⚠️ 重要提示 你必须提供API密钥或用户名和密码进行身份验证。

💻 使用示例

基础用法

你可以使用MCP客户端向Elasticsearch MCP Server发送自然语言查询，例如：

"What indices do I have in my Elasticsearch cluster?"

高级用法

你可以构建更复杂的查询，例如：

"Find all orders over $500 from last month."

🔧 技术细节

安全最佳实践

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

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

POST /_security/api_key
{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

故障排除

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

如果你遇到问题，请随时在GitHub仓库上打开一个问题。

📄 许可证

本项目采用Apache License 2.0许可。