JinDaGe - mcp_es MCP Details

article

README

🚀 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包。

配置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"
      }
    }
  }
}

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

本地开发

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

使用正确的Node.js版本
```
nvm use
```
安装依赖项
```
npm install
```
构建项目
```
npm run build
```

在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"
      }
    }
  }
}

使用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?"（哪些产品获得了最多的五星评价？）

工作原理

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

📦 安装指南

配置选项

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

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

| 环境变量 | 描述 | 是否必需 | |------|------|------| | ES_URL | 你的Elasticsearch实例URL | 是 | | ES_API_KEY | 用于身份验证的Elasticsearch API密钥 | 否 | | ES_USERNAME | 用于基本身份验证的Elasticsearch用户名 | 否 | | ES_PASSWORD | 用于基本身份验证的Elasticsearch密码 | 否 | | ES_CA_CERT | 用于Elasticsearch SSL/TLS的自定义CA证书的路径 | 否 |

💻 使用示例

基础用法

你可以使用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许可。

mcp_es