Este repositorio contiene características experimentales destinadas a la investigación y la evaluación y no están listas para producción.
Conéctese a sus datos de Elasticsearch directamente desde cualquier cliente MCP (como Claude Desktop) utilizando el Protocolo de contexto de modelo (MCP).
Este servidor conecta a los agentes con sus datos de Elasticsearch mediante el Protocolo de Contexto de Modelo. Le permite interactuar con sus índices de Elasticsearch mediante conversaciones en lenguaje natural.
list_indices : Lista todos los índices de Elasticsearch disponibles
get_mappings : obtiene asignaciones de campos para un índice Elasticsearch específico
search : Realiza una búsqueda de Elasticsearch con la consulta DSL proporcionada
get_shards : Obtener información de fragmentos para todos los índices o para índices específicos
Related MCP server: Elasticsearch MCP Server
Una instancia de Elasticsearch
Credenciales de autenticación de Elasticsearch (clave API o nombre de usuario/contraseña)
Cliente MCP (por ejemplo, Claude Desktop)
https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
[!TIP] La forma más sencilla de utilizar Elasticsearch MCP Server es a través del paquete npm publicado.
Configurar el cliente MCP
Abra su cliente MCP. Consulte la lista de clientes MCP . Aquí estamos configurando Claude Desktop.
Vaya a Configuración > Desarrollador > Servidores MCP
Haga clic Edit Config y agregue un nuevo servidor MCP con la siguiente configuración:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "npx",
"args": [
"-y",
"@elastic/mcp-server-elasticsearch"
],
"env": {
"ES_URL": "your-elasticsearch-url",
"ES_API_KEY": "your-api-key"
}
}
}
}Iniciar una conversación
Abra una nueva conversación en su cliente MCP
El servidor MCP debería conectarse automáticamente
Ahora puedes hacer preguntas sobre tus datos de Elasticsearch
El servidor MCP de Elasticsearch admite opciones de configuración para conectarse a su Elasticsearch:
[!NOTA] Debe proporcionar una clave API o un nombre de usuario y una contraseña para la autenticación.
Variable de entorno | Descripción | Requerido |
| La URL de su instancia de Elasticsearch | Sí |
| Clave API de Elasticsearch para autenticación | No |
| Nombre de usuario de Elasticsearch para autenticación básica | No |
| Contraseña de Elasticsearch para autenticación básica | No |
| Ruta al certificado CA personalizado para Elasticsearch SSL/TLS | No |
[!NOTA] Si desea modificar o ampliar el servidor MCP, siga estos pasos de desarrollo local.
Utilice la versión correcta de Node.js
nvm useInstalar dependencias
npm installConstruir el proyecto
npm run buildEjecutar localmente en la aplicación de escritorio Claude
Abra la aplicación de escritorio Claude
Vaya a Configuración > Desarrollador > Servidores MCP
Haga clic Edit Config y agregue un nuevo servidor MCP con la siguiente configuración:
{
"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"
}
}
}
}Depuración con MCP Inspector
ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspectorEsto iniciará el Inspector MCP, lo que le permitirá depurar y analizar solicitudes. Debería ver lo siguiente:
Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀¡Agradecemos las contribuciones de la comunidad! Para más información sobre cómo contribuir, consulta las Pautas de Contribución .
[!TIP] Aquí hay algunas consultas en lenguaje natural que puedes probar con tu cliente MCP.
"¿Qué índices tengo en mi clúster Elasticsearch?"
"Muéstrame las asignaciones de campos para el índice 'productos'".
"Encuentre todos los pedidos superiores a $500 del mes pasado".
"¿Qué productos recibieron más reseñas de 5 estrellas?"
El cliente MCP analiza su solicitud y determina qué operaciones de Elasticsearch son necesarias.
El servidor MCP lleva a cabo estas operaciones (enumerar índices, obtener asignaciones, realizar búsquedas).
El cliente MCP procesa los resultados y los presenta en un formato fácil de usar.
[!ADVERTENCIA] Evite usar privilegios de administrador del clúster. Cree claves de API dedicadas con alcance limitado y aplique un control de acceso preciso a nivel de índice para evitar el acceso no autorizado a los datos.
Puede crear una clave API de Elasticsearch dedicada con permisos mínimos para controlar el acceso a sus datos:
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"
]
}
]
}
}
}Este proyecto está licenciado bajo la Licencia Apache 2.0.
Asegúrese de que la configuración de su MCP sea correcta.
Verifique que su URL de Elasticsearch sea accesible desde su máquina.
Verifique que sus credenciales de autenticación (clave API o nombre de usuario/contraseña) tengan los permisos necesarios.
Si usa SSL/TLS con una CA personalizada, verifique que la ruta del certificado sea correcta y que el archivo sea legible.
Observe la salida del terminal para ver si hay mensajes de error.
Si encuentra problemas, no dude en abrir un problema en el repositorio de 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.
