Elasticsearch MCP Server

Elasticsearch MCP Server

English | 中文

用于从任何 MCP 客户端（如 Claude Desktop、Cursor）直接连接 Elasticsearch 集群的 MCP 服务。

此服务使用 Model Context Protocol 将 Agent 连接到您的 Elasticsearch 数据。您可以通过自然语言对话与 Elasticsearch 索引交互。

演示

功能概览

可用功能

集群管理

• elasticsearch_health：获取 Elasticsearch 集群健康状态，可选择包含索引级别的详细信息

索引操作

• list_indices：列出可用的 Elasticsearch 索引，支持正则表达式
• create_index：创建 Elasticsearch 索引，可选择设置和映射
• reindex：将数据从源索引重新索引到目标索引，可选择使用查询和脚本

映射管理

• get_mappings：获取指定 Elasticsearch 索引的字段映射
• create_mapping：创建或更新 Elasticsearch 索引的映射结构

搜索与数据操作

• search：使用提供的查询 DSL 执行 Elasticsearch 搜索
• bulk：向 Elasticsearch 索引批量写入数据

模板管理

• create_index_template：创建或更新索引模板
• get_index_template：获取索引模板的信息
• delete_index_template：删除索引模板

工作原理

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

开始使用

先决条件

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

安装与设置

使用已发布的 NPM 包

提示

使用已发布的 npm 包是使用 Elasticsearch MCP Server 最简单的方式。

1. 配置 MCP 客户端

   • 打开 MCP 客户端。请参阅 MCP 客户端列表，此处以配置 Claude Desktop 为例。
   • 前往 Settings > Developer > MCP Servers
   • 点击 Edit Config，并使用以下配置添加新的 MCP 服务：

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "@awesome-ai/elasticsearch-mcp"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

2. 开始对话

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

配置选项

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

说明

身份验证必须提供 API 密钥，或同时提供用户名和密码。

环境变量	描述	必填
ES_HOST	Elasticsearch 实例 URL，可填写单个 URL 或以逗号分隔的多个 URL（也支持旧版 HOST）	是
ES_API_KEY	用于身份验证的 Elasticsearch API 密钥（也支持旧版 API_KEY）	否
ES_USERNAME	用于基本身份验证的 Elasticsearch 用户名（也支持旧版 USERNAME）	否
ES_PASSWORD	用于基本身份验证的 Elasticsearch 密码（也支持旧版 PASSWORD）	否
ES_CA_CERT	Elasticsearch SSL/TLS 自定义 CA 证书的路径（也支持旧版 CA_CERT）	否

多 URL 配置

您可以配置多个 Elasticsearch 节点，以实现高可用性和负载均衡：

{
  "mcpServers": {
    "elasticsearch-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@awesome-ai/elasticsearch-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

客户端会自动处理已配置节点之间的故障转移和负载均衡。

本地开发

说明

如果你想修改或扩展 MCP Server，请按照以下本地开发步骤操作。

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

   nvm use
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 在 Claude Desktop App 中本地运行

   • 打开 Claude Desktop App
   • 前往 Settings > Developer > MCP Servers
   • 点击 Edit Config，并使用以下配置添加新的 MCP Server：

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "node",
         "args": [
           "/path/to/your/project/dist/index.js"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

5. 在 Cursor Editor 中本地运行

   • 打开 Cursor Editor
   • 前往 Cursor Settings > MCP
   • 点击 Add new global MCP Server，并使用以下配置添加新的 MCP Server：

   {
     "mcpServers": {
       "elasticsearch-mcp": {
         "command": "node",
         "args": [
           "/path/to/your/project/dist/index.js"
         ],
         "env": {
           "ES_HOST": "your-elasticsearch-host",
           "ES_API_KEY": "your-api-key"
         }
       }
     }
   }
   

6. 使用 MCP Inspector 调试

   ES_HOST=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector
   

   这将启动 MCP Inspector，以便你调试和分析请求。你应该会看到：

   Starting MCP inspector...
   ⚙️ Proxy server listening on port 6277
   🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
   

示例查询

提示

以下是一些你可以通过 MCP 客户端尝试的自然语言查询。

集群管理

• "我的 Elasticsearch 集群的健康状态如何？"
• "我的集群中有多少个活动节点？"

索引操作

• "我的 Elasticsearch 集群中有哪些索引？"
• "创建一个名为 'users' 的新索引，包含 3 个分片和 1 个副本。"
• "将数据从 'old_index' 重新索引到 'new_index'。"

映射管理

• "显示 'products' 索引的字段映射。"
• "为 'products' 索引添加一个名为 'tags' 的 keyword 类型字段。"

搜索与数据操作

• "查找上个月所有金额超过 $500 的订单。"
• "哪些产品收到的 5 星评价最多？"
• "将这些客户记录批量导入 'customers' 索引。"

模板管理

• "为日志创建一个索引模板，模式为 'logs-*'。"
• "显示我的所有索引模板。"
• "删除 'outdated_template' 索引模板。"

如果遇到问题，欢迎在 GitHub 仓库中提交 issue。