AI导哈

Elasticsearch自然语言查询服务

通过模型上下文协议(MCP)实现Elasticsearch数据的自然语言交互，支持索引查询、映射获取等功能。

  • by rybalov
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 rybalov/mcp-server-elasticsearch

使用说明

Elasticsearch MCP服务器

此存储库包含用于研究和评估的实验功能，尚未投入生产。

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

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

可用工具

  • list_indices：列出所有可用的Elasticsearch索引
  • get_mappings：获取特定Elasticsearch索引的字段映射
  • search：使用提供的查询DSL执行Elasticsearch搜索。支持突出显示、查询分析和查询解释。
  • get_shards：获取所有或特定索引的分片信息

先决条件

  • Elasticsearch实例
  • Elasticsearch身份验证凭据（API密钥或用户名/密码）
  • Docker（或OCI运行时）
  • MCP客户端（如克劳德桌面）

演示

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

安装和设置

使用Docker

  1. 配置MCP客户端

    • 打开您的MCP客户端。请参阅 MCP客户端列表，这里我们正在配置Claude Desktop。
    • 首选 设置>开发人员>MCP服务器
    • 点击 Edit Config 并添加具有以下配置的新MCP服务器：
    {
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_URL",
        "-e", "ES_API_KEY",
        "docker.elastic.co/mcp/elasticsearch", "stdio"
      ],
      "env": {
        "ES_URL": "<your-elasticsearch-url>",
        "ES_API_KEY": "<your-api-key>"
      }
    }
  }
}

  2. 开始对话

    • 在MCP客户端中打开新对话
    • MCP服务器应自动连接
    • 现在，您可以询问有关Elasticsearch数据的问题

使用已发布的NPM包

  1. 配置MCP客户端

    • 打开您的MCP客户端。请参阅 MCP客户端列表，这里我们正在配置Claude Desktop。
    • 首选 设置>开发人员>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>",
        "OTEL_LOG_LEVEL": "none"
      }
    }
  }
}

  2. 开始对话

    • 在MCP客户端中打开新对话
    • MCP服务器应自动连接
    • 现在，您可以询问有关Elasticsearch数据的问题

配置选项

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

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

环境变量 描述 必填
ES_URL 您的Elasticsearch实例URL 是
ES_API_KEY 用于身份验证的Elasticsearch API密钥 否
ES_USERNAME 用于基本身份验证的Elasticsearch用户名 否
ES_PASSWORD 用于基本身份验证的Elasticsearch密码 否
ES_CA_CERT Elasticsearch SSL/TLS的自定义CA证书路径 否
ES_SSL_SKIP_VERIFY 设置为“1”或“true”以跳过SSL证书验证 否
ES_PATH_PREFIX Elasticsearch实例的路径前缀在非根路径上公开 否
ES_VERSION 服务器假定Elasticsearch 9.x。设置为 8 目标Elasticsearch 8.x 否

在当地发展

[！注意] 如果要修改或扩展MCP服务器，请按照以下本地开发步骤进行操作。

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

    nvm use

  2. 再进行

    npm install

  3. 构建项目

    npm run build

  4. 在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",
        "OTEL_LOG_LEVEL": "none"
      }
    }
  }
}

  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 🚀

贡献

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

示例问题

[！提示] 以下是您可以使用MCP客户端尝试的一些自然语言查询。

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

运作原理

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

安全最佳实践

[！警告] 避免使用集群管理员权限。创建范围有限的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"
          ]
        }
      ]
    }
  }
}

许可证

此项目根据Apache许可证2.0获得许可。

故障排除

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

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

相关 MCP