MCP Es

🚀 Elasticsearch MCP Server

本仓库包含用于研究和评估的实验性功能，尚未达到生产就绪状态。借助模型上下文协议（MCP），可直接从任何 MCP 客户端（如 Claude Desktop）连接到你的 Elasticsearch 数据。此服务器使用模型上下文协议将代理连接到你的 Elasticsearch 数据，允许你通过自然语言对话与 Elasticsearch 索引进行交互。

🚀 快速开始

本项目允许你通过 MCP 客户端与 Elasticsearch 数据进行自然语言交互。以下是使用本项目的基本步骤：

1. 确保你已具备所需的先决条件。
2. 选择合适的安装和设置方式。
3. 开始与 Elasticsearch 数据进行对话。

✨ 主要特性

可用工具

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

工作原理

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

📦 安装指南

使用发布的 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 数据的问题。

配置选项

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

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

本地开发

⚠️ 重要提示 如果你想修改或扩展 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 🚀

💻 使用示例

基础用法

你可以在 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 URL 可从你的机器访问。
• 检查你的身份验证凭据（API 密钥或用户名/密码）是否具有必要的权限。
• 如果你使用自定义 CA 进行 SSL/TLS 连接，请验证证书路径是否正确且文件可读。
• 查看终端输出以获取错误消息。

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

🔧 技术细节

工作原理

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 版。