Skip to main content
Glama
Elasticsearch MCP Server

Elasticsearch MCP Server

Elasticsearch/OpenSearch MCP Server

Trust Score

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ásica

  • ELASTICSEARCH_PASSWORD: Contraseña para autenticación básica

  • OPENSEARCH_USERNAME: Nombre de usuario para autenticación básica de OpenSearch

  • OPENSEARCH_PASSWORD: Contraseña para autenticación básica de OpenSearch

Autenticación con clave API (solo Elasticsearch) - Recomendada

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 opcional cluster.

  • 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 omite cluster (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 encabezado Authorization: Bearer <MCP_API_KEY>.

Notas de seguridad importantes:

  • La autenticación solo es aplicable para transportes HTTP (sse, streamable-http). El transporte stdio usa comunicación de proceso local y no requiere autenticación.

  • Si MCP_API_KEY no 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 a true para 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_index

    • delete_index

  • Operaciones de documentos:

    • index_document

    • delete_document

    • delete_by_query

  • Operaciones de flujo de datos:

    • create_data_stream

    • delete_data_stream

  • Operaciones de alias:

    • put_alias

    • delete_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=gcf

structuredContent 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.

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 -d

El 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 /sse

Opció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 /sse

Streamable 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 /mcp

Opció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 /mcp

Compatibilidad

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-es7

Si 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-server

Despliegue 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 tools
analyze_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

    B3.3/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Connects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.
      4
      Apache 2.0
    • F
      license
      B
      quality
      D
      maintenance
      Connects 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.
      10
      17 npm
      MIT