Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP Server
Descripción general
Una implementación de servidor del Model Context Protocol (MCP) que proporciona interacción con Elasticsearch y OpenSearch. Este servidor permite buscar documentos, analizar índices y gestionar el clúster mediante un conjunto de herramientas.
Related MCP server: Elasticsearch MCP Server
Demo
https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
Características
Operaciones generales
general_api_request: Realiza una solicitud HTTP API general. Usa esta herramienta para cualquier API de Elasticsearch/OpenSearch que no tenga una herramienta dedicada.
Operaciones de índice
list_indices: Lista todos los índices.get_index: Devuelve información (mapeos, ajustes, alias) sobre uno o más índices.create_index: Crea un nuevo índice.delete_index: Elimina un índice.create_data_stream: Crea un nuevo flujo de datos (requiere una plantilla de índice coincidente).get_data_stream: Obtiene información sobre uno o más flujos de datos.delete_data_stream: Elimina uno o más flujos de datos y sus índices subyacentes.
Operaciones de documentos
search_documents: Busca documentos.index_document: Crea o actualiza un documento en el índice.get_document: Obtiene un documento por ID.delete_document: Elimina un documento por ID.delete_by_query: Elimina documentos que coinciden con la consulta proporcionada.
Operaciones de clúster
get_cluster_health: Devuelve información básica sobre la salud del clúster.get_cluster_stats: Devuelve una visión general de alto nivel de las estadísticas del clúster.
Operaciones de alias
list_aliases: Lista todos los alias.get_alias: Obtiene información de alias para un índice específico.put_alias: Crea o actualiza un alias para un índice específico.delete_alias: Elimina un alias para un índice específico.
Operaciones de analizador
analyze_text: Analiza texto usando un analizador especificado o una cadena de análisis personalizada. Útil para depurar consultas de búsqueda y comprender cómo se tokeniza el texto.
Configurar variables de entorno
El servidor MCP admite las siguientes variables de entorno:
Autenticación básica (usuario/contraseña)
ELASTICSEARCH_USERNAME: Nombre de usuario para autenticación básicaELASTICSEARCH_PASSWORD: Contraseña para autenticación básicaOPENSEARCH_USERNAME: Nombre de usuario para autenticación básica de OpenSearchOPENSEARCH_PASSWORD: Contraseña para autenticación básica de OpenSearch
Autenticación con clave API (solo Elasticsearch) - Recomendada
ELASTICSEARCH_API_KEY: Clave API para la autenticación de Elasticsearch o Elastic Cloud.
Configuración de conexión
ELASTICSEARCH_HOSTS/OPENSEARCH_HOSTS: Lista de hosts separados por comas (por defecto:https://localhost:9200)ELASTICSEARCH_CLUSTERS/OPENSEARCH_CLUSTERS: Objeto JSON en línea para configuraciones de clúster con nombre. Cuando se establece, las herramientas pueden apuntar a un clúster específico con el parámetro opcionalcluster.ELASTICSEARCH_CLUSTERS_FILE/OPENSEARCH_CLUSTERS_FILE: Ruta a un archivo JSON con el objeto de clústeres. Se recomienda cuando la configuración está incrustada dentro de otro archivo JSON (por ejemplo, la configuración del cliente MCP) porque evita el escape de JSON dentro de JSON. Tiene prioridad sobre la variable en línea cuando ambas están configuradas.DEFAULT_CLUSTER: Nombre de clúster predeterminado a usar cuando se configura multi-clúster y una llamada de herramienta omitecluster(por defecto, el primer clúster configurado).VERIFY_CERTS: Si se deben verificar los certificados SSL (por defecto:false)REQUEST_TIMEOUT: Tiempo de espera de solicitud en segundos (opcional, usa el valor predeterminado del cliente si no se establece)
Configuración de múltiples clústeres
Por defecto, el servidor usa un único clúster de Elasticsearch de ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD y ELASTICSEARCH_API_KEY, o un único clúster de OpenSearch de OPENSEARCH_HOSTS, OPENSEARCH_USERNAME y OPENSEARCH_PASSWORD. Para configurar múltiples clústeres con nombre, establece ELASTICSEARCH_CLUSTERS (o OPENSEARCH_CLUSTERS) como un objeto JSON dentro de la configuración del servidor MCP. Debido a que el valor es una cadena JSON incrustada en otro archivo JSON, las comillas internas deben escaparse:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uvx",
"args": [
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_CLUSTERS": "{\"prod\": {\"hosts\": [\"https://prod-es:9200\"], \"api_key\": \"<PROD_API_KEY>\", \"verify_certs\": true}, \"staging\": {\"hosts\": [\"https://staging-es:9200\"], \"username\": \"elastic\", \"password\": \"<STAGING_PASSWORD>\"}}",
"DEFAULT_CLUSTER": "prod"
}
}
}
}Para una mejor legibilidad, apunta ELASTICSEARCH_CLUSTERS_FILE (o OPENSEARCH_CLUSTERS_FILE) a un archivo JSON independiente en su lugar. El valor es solo una ruta, por lo que evita el escape de JSON dentro de JSON:
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uvx",
"args": [
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_CLUSTERS_FILE": "/etc/mcp/es-clusters.json",
"DEFAULT_CLUSTER": "prod"
}
}
}
}/etc/mcp/es-clusters.json:
{
"prod": {
"hosts": ["https://prod-es:9200"],
"api_key": "<PROD_API_KEY>",
"verify_certs": true
},
"staging": {
"hosts": ["https://staging-es:9200"],
"username": "elastic",
"password": "<STAGING_PASSWORD>"
}
}Cada herramienta acepta un parámetro opcional cluster. Si se omite, el servidor usa DEFAULT_CLUSTER. Cuando DEFAULT_CLUSTER no está configurado, el primer clúster en el objeto JSON se usa como predeterminado. Una llamada de herramienta que apunta a un clúster específico se ve así:
{
"cluster": "staging",
"index": "logs-*",
"body": {
"query": {
"match_all": {}
}
}
}Autenticación del servidor MCP (solo transportes HTTP)
Cuando se ejecuta el servidor MCP con transportes basados en HTTP (SSE o Streamable HTTP), puedes habilitar la autenticación con token Bearer para proteger el servidor de accesos no autorizados.
MCP_API_KEY: Clave API para la autenticación del servidor MCP. Los clientes deben incluir el encabezadoAuthorization: Bearer <MCP_API_KEY>.
Notas de seguridad importantes:
La autenticación solo es aplicable para transportes HTTP (
sse,streamable-http). El transportestdiousa comunicación de proceso local y no requiere autenticación.Si
MCP_API_KEYno está configurada, el servidor MCP será accesible sin autenticación. Esto es un riesgo de seguridad al exponer el servidor a través de una red.Para implementaciones de producción con transportes HTTP, siempre establece
MCP_API_KEY.
# Generate a secure API key (example using openssl)
export MCP_API_KEY=$(openssl rand -base64 32)
# Or set a custom API key
export MCP_API_KEY="your-secure-api-key-here"Deshabilitar operaciones de alto riesgo
DISABLE_HIGH_RISK_OPERATIONS: Establecer atruepara deshabilitar todas las operaciones de escritura (por defecto:false)DISABLE_OPERATIONS: Lista separada por comas de operaciones específicas a deshabilitar (opcional, usa la lista de operaciones de escritura predeterminada si no se establece)
Cuando DISABLE_HIGH_RISK_OPERATIONS se establece a true, todas las herramientas MCP que realizan operaciones de escritura quedan completamente ocultas del cliente MCP. En este modo, las siguientes herramientas MCP están deshabilitadas por defecto.
Operaciones de índice:
create_indexdelete_index
Operaciones de documentos:
index_documentdelete_documentdelete_by_query
Operaciones de flujo de datos:
create_data_streamdelete_data_stream
Operaciones de alias:
put_aliasdelete_alias
Operaciones generales de API:
general_api_request
Opcionalmente, puedes especificar una lista separada por comas de operaciones a deshabilitar en la variable de entorno DISABLE_OPERATIONS.
# Disable High-Risk Operations
export DISABLE_HIGH_RISK_OPERATIONS=true
# Disable specific operations only
export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"Codificación de respuesta GCF (opcional)
Opta por serializar los payloads de resultados de herramientas como GCF (Graph Compact Format), un formato de cable optimizado para tokens, en el bloque de contenido que el modelo lee. Elasticsearch devuelve grandes conjuntos de registros uniformes (resultados de búsqueda, buckets de agregaciones, mapeos), la forma que GCF comprime mejor: en respuestas representativas es ~39% menos tokens que JSON compacto (40% en resultados de búsqueda), sin pérdida.
export RESPONSE_FORMAT=gcfstructuredContent se conserva sin cambios, por lo que el esquema de salida declarado de una herramienta aún se valida y cualquier cliente no modelo sigue recibiendo JSON; solo el bloque de texto orientado al modelo se recodifica. La codificación es a prueba de fallos: cualquier error, incluido un valor fuera del dominio numérico canónico int64 de GCF (que GCF rechaza en lugar de aproximar silenciosamente), deja el resultado JSON original intacto, por lo que una llamada de herramienta nunca se descarta por codificación. El comportamiento predeterminado no cambia cuando RESPONSE_FORMAT no está configurado.
Reproduce la comparación de tokens: uv run --with tiktoken python benchmarks/gcf_benchmark.py.
Iniciar clúster de Elasticsearch/OpenSearch
Inicia el clúster de Elasticsearch/OpenSearch usando Docker Compose:
# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d
# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -dEl nombre de usuario predeterminado de Elasticsearch es elastic y la contraseña es test123. El nombre de usuario predeterminado de OpenSearch es admin y la contraseña es admin.
Puedes acceder a Kibana/OpenSearch Dashboards desde http://localhost:5601.
Stdio
Opción 1: Usando uvx
Usar uvx instalará automáticamente el paquete desde PyPI, sin necesidad de clonar el repositorio localmente. Agrega la siguiente configuración al archivo de configuración claude_desktop_config.json.
// For Elasticsearch with username/password
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uvx",
"args": [
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_HOSTS": "https://localhost:9200",
"ELASTICSEARCH_USERNAME": "elastic",
"ELASTICSEARCH_PASSWORD": "test123"
}
}
}
}
// For Elasticsearch with API key
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uvx",
"args": [
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_HOSTS": "https://localhost:9200",
"ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
}
}
}
}
// For OpenSearch
{
"mcpServers": {
"opensearch-mcp-server": {
"command": "uvx",
"args": [
"opensearch-mcp-server"
],
"env": {
"OPENSEARCH_HOSTS": "https://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin"
}
}
}
}Opción 2: Usando uv con desarrollo local
Usar uv requiere clonar el repositorio localmente y especificar la ruta al código fuente. Agrega la siguiente configuración al archivo de configuración claude_desktop_config.json de Claude Desktop.
// For Elasticsearch with username/password
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uv",
"args": [
"--directory",
"path/to/elasticsearch-mcp-server",
"run",
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_HOSTS": "https://localhost:9200",
"ELASTICSEARCH_USERNAME": "elastic",
"ELASTICSEARCH_PASSWORD": "test123"
}
}
}
}
// For Elasticsearch with API key
{
"mcpServers": {
"elasticsearch-mcp-server": {
"command": "uv",
"args": [
"--directory",
"path/to/elasticsearch-mcp-server",
"run",
"elasticsearch-mcp-server"
],
"env": {
"ELASTICSEARCH_HOSTS": "https://localhost:9200",
"ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
}
}
}
}
// For OpenSearch
{
"mcpServers": {
"opensearch-mcp-server": {
"command": "uv",
"args": [
"--directory",
"path/to/elasticsearch-mcp-server",
"run",
"opensearch-mcp-server"
],
"env": {
"OPENSEARCH_HOSTS": "https://localhost:9200",
"OPENSEARCH_USERNAME": "admin",
"OPENSEARCH_PASSWORD": "admin"
}
}
}
}SSE
Opción 1: Usando uvx
# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"
# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uvx elasticsearch-mcp-server --transport sse
# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sseOpción 2: Usando uv
# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uv run src/server.py elasticsearch-mcp-server --transport sse
# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sseStreamable HTTP
Opción 1: Usando uvx
# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"
# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"
# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uvx elasticsearch-mcp-server --transport streamable-http
# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcpOpción 2: Usando uv
# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uv run src/server.py elasticsearch-mcp-server --transport streamable-http
# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcpCompatibilidad
El servidor MCP es compatible con Elasticsearch 7.x, 8.x y 9.x. Por defecto, usa el cliente de Elasticsearch 8.x (sin sufijo).
MCP Server | Elasticsearch |
elasticsearch-mcp-server-es7 | Elasticsearch 7.x |
elasticsearch-mcp-server | Elasticsearch 8.x |
elasticsearch-mcp-server-es9 | Elasticsearch 9.x |
opensearch-mcp-server | OpenSearch 1.x, 2.x, 3.x |
Para usar el cliente de Elasticsearch 7.x, ejecuta la variante elasticsearch-mcp-server-es7. Para Elasticsearch 9.x, usa elasticsearch-mcp-server-es9. Por ejemplo:
uvx elasticsearch-mcp-server-es7Si deseas ejecutar diferentes variantes de Elasticsearch (por ejemplo, 7.x o 9.x) localmente, simplemente actualiza la dependencia elasticsearch en pyproject.toml y luego inicia el servidor con:
uv run src/server.py elasticsearch-mcp-serverDespliegue en Kubernetes
La imagen Docker se publica en ghcr.io/cr7258/elasticsearch-mcp-server y el chart de Helm está disponible como artefacto OCI en el repositorio oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server.
Para instrucciones completas de instalación, referencia de configuración y ejemplos de uso, consulta el README del chart de Helm.
Licencia
Este proyecto está licenciado bajo la Apache License Version 2.0 - consulta el archivo LICENSE para más detalles.
Available Tools
20 toolsanalyze_textB
Analyze text to see how it would be tokenized.
Use this tool to understand how Elasticsearch/OpenSearch tokenizes and transforms text using analyzers. This is essential for debugging search queries and understanding why certain documents match or don't match.
Inputs: text (required), index, filter, cluster, +5 more. Returns: object
create_data_streamB
Create a new data stream.
This creates a new data stream with the specified name. The data stream must have a matching index template before creation.
Inputs: name (required), cluster. Returns: object
create_indexC
Create a new index.
Inputs: index (required), body, cluster. Returns: object
delete_aliasC
Delete an alias for a specific index.
Inputs: name (required), index (required), cluster. Returns: object
delete_by_queryC
Deletes documents matching the provided query.
Inputs: body (required), index (required), cluster. Returns: object
delete_data_streamA
Delete one or more data streams.
Permanently deletes the specified data streams and all their backing indices.
Inputs: name (required), cluster. Returns: object
delete_documentC
Delete a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
delete_indexC
Delete an index.
Inputs: index (required), cluster. Returns: object
general_api_requestA
Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
Inputs: path (required), method (required), body, params, +1 more.
get_aliasC
Get alias information for a specific index.
Inputs: index (required), cluster. Returns: object
get_cluster_healthC
Returns basic information about the health of the cluster.
Inputs: cluster. Returns: object
get_cluster_statsB
Returns high-level overview of cluster statistics.
Inputs: cluster. Returns: object
get_data_streamC
Get information about one or more data streams.
Retrieves configuration, mappings, settings, and other information about the specified data streams.
Inputs: name, cluster. Returns: object
get_documentC
Get a document by ID.
Inputs: id (required), index (required), cluster. Returns: object
get_indexB
Returns information (mappings, settings, aliases) about one or more indices.
Inputs: index (required), cluster. Returns: object
index_documentC
Creates or updates a document in the index.
Inputs: index (required), document (required), id, cluster. Returns: object
list_aliasesB
List all aliases.
Inputs: cluster. Returns: result
list_indicesC
List all indices.
Inputs: cluster. Returns: result
put_aliasC
Create or update an alias for a specific index.
Inputs: body (required), name (required), index (required), cluster. Returns: object
search_documentsC
Search for documents.
Inputs: body (required), index (required), cluster. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a clearly distinct resource and action (index, document, alias, data stream, cluster, analysis, or generic API). Overlaps like get_index vs list_indices and get_alias vs list_aliases are cleanly separated by specificity. The general_api_request fallback is explicitly scoped to APIs without dedicated tools, so it does not create real misselection risk.
Tools follow a consistent snake_case verb_noun convention (create_index, delete_document, get_cluster_health, put_alias, etc.). The only minor exception is general_api_request, but it still fits the overall readable naming style. There is no mixing of camelCase or conflicting verb patterns.
At 20 tools, the surface is slightly heavy by the usual 3–15 guideline, but Elasticsearch is a broad domain and each tool covers a meaningful resource area. The set avoids extreme bloat and does not include redundant operations.
Core CRUD and lifecycle coverage exists for indices, documents, aliases, data streams, and cluster inspection, with search and text analysis included. Notable gaps remain—such as dedicated index template management (required for data streams), bulk operations, and update-by-query—but the general_api_request tool provides a workaround for any missing API.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.2-
- AlicenseBqualityDmaintenanceConnects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.4Apache 2.0
- FlicenseBqualityDmaintenanceConnects to Elasticsearch clusters through the Model Context Protocol, enabling natural language querying and management of Elasticsearch data. Provides tools to search indices, list available indices, and retrieve index mappings.3-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT