该存储库包含用于研究和评估的实验性功能，尚不适用于生产。
使用模型上下文协议 (MCP) 直接从任何 MCP 客户端（如 Claude Desktop）连接到您的 Elasticsearch 数据。
该服务器使用模型上下文协议 (MCP) 将代理连接到您的 Elasticsearch 数据。它允许您通过自然语言对话与您的 Elasticsearch 索引进行交互。
list_indices ：列出所有可用的 Elasticsearch 索引
get_mappings ：获取特定 Elasticsearch 索引的字段映射
search ：使用提供的查询 DSL 执行 Elasticsearch 搜索
get_shards ：获取所有或特定索引的分片信息
Related MCP server: Elasticsearch MCP Server
Elasticsearch 实例
Elasticsearch 身份验证凭据（API 密钥或用户名/密码）
MCP 客户端（例如 Claude Desktop）
https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
[!TIP] 使用 Elasticsearch MCP Server 最简单的方法是通过已发布的 npm 包。
配置 MCP 客户端
打开您的 MCP 客户端。查看MCP 客户端列表，这里我们正在配置 Claude 桌面。
前往**“设置”>“开发者”>“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"
}
}
}
}开始对话
在 MCP 客户端中打开新对话
MCP 服务器应该会自动连接
您现在可以询问有关 Elasticsearch 数据的问题
Elasticsearch MCP 服务器支持配置选项来连接到您的 Elasticsearch：
[!NOTE] 您必须提供 API 密钥或用户名和密码进行身份验证。
环境变量 | 描述 | 必需的 |
| 您的 Elasticsearch 实例 URL | 是的 |
| 用于身份验证的 Elasticsearch API 密钥 | 不 |
| 用于基本身份验证的 Elasticsearch 用户名 | 不 |
| Elasticsearch 基本身份验证密码 | 不 |
| Elasticsearch SSL/TLS 的自定义 CA 证书路径 | 不 |
[!NOTE] 如果您想修改或扩展 MCP 服务器，请按照这些本地开发步骤操作。
使用正确的 Node.js 版本
nvm use安装依赖项
npm install构建项目
npm run build在 Claude 桌面应用程序中本地运行
打开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"
}
}
}
}使用 MCP Inspector 进行调试
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 🚀我们欢迎社区的贡献！有关如何贡献的详细信息，请参阅贡献指南。
[!TIP] 您可以使用 MCP 客户端尝试以下一些自然语言查询。
“我的 Elasticsearch 集群中有哪些索引？”
“显示‘产品’索引的字段映射。”
“查找上个月所有超过 500 美元的订单。”
“哪些产品获得最多五星评价？”
MCP 客户端分析您的请求并确定需要哪些 Elasticsearch 操作。
MCP 服务器执行这些操作（列出索引、获取映射、执行搜索）。
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 License 2.0 许可。
确保您的 MCP 配置正确。
验证您的 Elasticsearch URL 是否可以从您的机器访问。
检查您的身份验证凭据（API 密钥或用户名/密码）是否具有必要的权限。
如果使用带有自定义 CA 的 SSL/TLS，请验证证书路径是否正确以及文件是否可读。
查看终端输出中的错误消息。
如果您遇到问题，请随时在 GitHub 存储库上打开问题。
Get field mappings for a specific Elasticsearch index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to get mappings for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Get field mappings', implying read-only but not disclosing permissions, side effects, or behavior like error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention what the response contains; it is adequate but minimal for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'index' has a description; the tool description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'field mappings' for a specific Elasticsearch index, clearly distinguishing from siblings like create_mapping or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; for example, it doesn't explain how it differs from create_mapping or search in terms of use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Elasticsearch indices
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read operation, it doesn't specify whether this requires special permissions, returns paginated results, includes hidden/system indices, or provides any metadata beyond names. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple listing tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation without output schema, the description provides the minimum viable information about what the tool does. However, given the lack of annotations and sibling tools with potentially overlapping functionality, more context about when to use this versus alternatives would be helpful. The description is complete enough for basic understanding but leaves operational context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't mention parameters since none exist. A baseline of 4 is appropriate for zero-parameter tools where the schema handles all parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available Elasticsearch indices'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_mappings' or 'search' - it's unclear if this is a simple listing versus more detailed metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_mappings' or 'search'. There's no indication of whether this is for administrative purposes, discovery, or as a prerequisite for other operations. The agent must infer usage context from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an Elasticsearch search with the provided query DSL. Highlights are always enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Name of the Elasticsearch index to search | |
| queryBody | Yes | Complete Elasticsearch query DSL object that can include query, size, from, sort, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only mentions highlights are always enabled. No disclosure of read-only nature, error handling, pagination, or required permissions. With no annotations, more behavioral detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action. No wasted words, though could be expanded with important behavioral notes without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of Elasticsearch searches (query DSL), the description lacks return format, pagination behavior, and error context. Incomplete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes both parameters. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs an Elasticsearch search with query DSL, identifying the specific verb and resource. Distinguishes from sibling tools that handle index management, bulk operations, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings (e.g., bulk, list_indices) or when not to use it. Lacks prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_mappingslist_indicessearchScored across 3 tools
Each tool has a clearly distinct purpose: get_mappings retrieves field mappings for a specific index, list_indices enumerates all indices, and search performs query-based searches. There is no overlap in functionality, making tool selection unambiguous.
All tool names follow a consistent verb_noun pattern (get_mappings, list_indices, search), with clear and descriptive verbs that align with their actions. No deviations or mixed conventions are present.
With only 3 tools, the set feels thin for an Elasticsearch server, as it lacks essential operations like creating/deleting indices, updating mappings, or performing CRUD operations on documents. While the tools are well-defined, the count is borderline for the domain's scope.
There are significant gaps in the tool surface for Elasticsearch functionality. Missing operations include index creation/deletion, document indexing/updating/deleting, and cluster management. This incompleteness will likely cause agent failures when attempting full workflows.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Connect Claude, Cursor, or ChatGPT to your business data. Ask questions, get answers.
Build and manage AI-native customer support agents from Claude or any MCP client.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
