Elasticsearch/OpenSearch

Un servidor MCP para interactuar con clústeres de Elasticsearch y OpenSearch.

Documentación

Servidor MCP de Elasticsearch/OpenSearch

Descripción general

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que proporciona interacción con Elasticsearch y OpenSearch. Este servidor permite buscar documentos, analizar índices y gestionar el clúster a través de un conjunto de herramientas.

Demostración

https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

Características

Operaciones generales

general_api_request: Realiza una solicitud HTTP API general. Utilice 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, configuraciones, 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 de respaldo.

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 el estado de salud del clúster.
get_cluster_stats: Devuelve una descripció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 utilizando 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 (nombre de 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

ELASTICSEARCH_API_KEY: Clave API para autenticación de Elasticsearch o Elastic Cloud.

Configuración de conexión

ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Lista de hosts separados por comas (predeterminado: 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. Recomendado cuando la configuración está incrustada dentro de otro archivo JSON (por ejemplo, la configuración del cliente MCP) porque evita el escape JSON-en-JSON. Tiene prioridad sobre la variable en línea cuando ambas están configuradas.
DEFAULT_CLUSTER: Nombre de clúster predeterminado para usar cuando la configuración de múltiples clústeres está establecida y una llamada de herramienta omite cluster (se establece por defecto al primer clúster configurado).
VERIFY_CERTS: Si verificar certificados SSL (predeterminado: 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

De forma predeterminada, 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, establezca ELASTICSEARCH_CLUSTERS (o OPENSEARCH_CLUSTERS) a 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, apunte 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 JSON-en-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 dirigida 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)

Al ejecutar el servidor MCP con transportes basados en HTTP (SSE o HTTP Streamable), puede habilitar la autenticación con token Bearer para proteger el servidor de accesos no autorizados.

MCP_API_KEY: Clave API para 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 utiliza comunicación de proceso local y no requiere autenticación.
Si MCP_API_KEY no está configurado, 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 configure 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 (predeterminado: false)
DISABLE_OPERATIONS: Lista separada por comas de operaciones específicas para deshabilitar (opcional, usa la lista de operaciones de escritura predeterminada si no se establece)

Cuando DISABLE_HIGH_RISK_OPERATIONS se establece en 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 de forma predeterminada.

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, puede especificar una lista separada por comas de operaciones para 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)

Opte por serializar las cargas útiles de resultados de herramientas como GCF (Formato Compacto de Gráfico), 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, cubos de agregación, 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érdidas.

export RESPONSE_FORMAT=gcf

structuredContent se conserva sin cambios, por lo que el esquema de salida declarado de una herramienta sigue siendo válido y cualquier cliente que no sea 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.

Reproduzca la comparación de tokens: uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Iniciar clúster de Elasticsearch/OpenSearch

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

Puede 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. Agregue la siguiente configuración al archivo de configuración de 's 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. Agregue la siguiente configuración al archivo de configuración de Claude Desktop claude_desktop_config.json.

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

HTTP Streamable

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. De forma predeterminada, usa el cliente de Elasticsearch 8.x (sin sufijo).

Servidor MCP	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, ejecute la variante elasticsearch-mcp-server-es7. Para Elasticsearch 9.x, use elasticsearch-mcp-server-es9. Por ejemplo:

uvx elasticsearch-mcp-server-es7

Si desea ejecutar diferentes variantes de Elasticsearch (por ejemplo, 7.x o 9.x) localmente, simplemente actualice la versión de dependencia elasticsearch en pyproject.toml, luego inicie el servidor con:

uv run src/server.py elasticsearch-mcp-server

Implementación en Kubernetes

La imagen de Docker se publica en ghcr.io/cr7258/elasticsearch-mcp-server y el gráfico de Helm está disponible como un 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, consulte el README del gráfico de Helm.

Licencia

Este proyecto está licenciado bajo la Licencia Apache Versión 2.0; consulte el archivo LICENCIA para más detalles.