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 mediante 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 genérica a la API. Utilice esta herramienta para cualquier API de Elasticsearch/OpenSearch que no tenga una herramienta dedicada.

Operaciones de índices

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 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 los 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 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 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 (usuario/contraseña)

ELASTICSEARCH_USERNAME: Usuario para autenticación básica
ELASTICSEARCH_PASSWORD: Contraseña para autenticación básica
OPENSEARCH_USERNAME: Usuario para autenticación básica de OpenSearch
OPENSEARCH_PASSWORD: Contraseña para autenticación básica de OpenSearch

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

ELASTICSEARCH_API_KEY: Clave de 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-dentro-de-JSON. Tiene prioridad sobre la variable en línea cuando ambas están establecidas.
DEFAULT_CLUSTER: Nombre de clúster predeterminado que se utiliza cuando la configuración de múltiples clústeres está establecida y una llamada a herramienta omite cluster (por defecto, el primer clúster configurado).
VERIFY_CERTS: Si se deben verificar los certificados SSL (predeterminado: false)
REQUEST_TIMEOUT: Tiempo de espera de solicitud en segundos (opcional, utiliza el valor predeterminado del cliente si no se establece)

Configuración de múltiples clústeres

De forma predeterminada, el servidor utiliza un único clúster de Elasticsearch a partir de ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD y ELASTICSEARCH_API_KEY, o un único clúster de OpenSearch a partir de OPENSEARCH_HOSTS, OPENSEARCH_USERNAME y OPENSEARCH_PASSWORD. Para configurar múltiples clústeres con nombre, establezca 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, apunte ELASTICSEARCH_CLUSTERS_FILE (o OPENSEARCH_CLUSTERS_FILE) a un archivo JSON independiente. El valor es solo una ruta, por lo que evita el escape 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 utiliza DEFAULT_CLUSTER. Cuando DEFAULT_CLUSTER no está establecido, el primer clúster del objeto JSON se utiliza como predeterminado. Una llamada a 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 de 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 utiliza comunicación local entre procesos y no requiere autenticación.
Si MCP_API_KEY no está establecido, 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, establezca siempre 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: Establézcalo en true para deshabilitar todas las operaciones de escritura (predeterminado: false)
DISABLE_OPERATIONS: Lista separada por comas de operaciones específicas para deshabilitar (opcional, utiliza 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 índices:
- create_index
- delete_index
Operaciones de documentos:
- index_document
- delete_document
- delete_by_query
Operaciones de flujos 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"

Iniciar el 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 usuario predeterminado de Elasticsearch es elastic y la contraseña es test123. El 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, utiliza 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 la 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 LICENSE para más detalles.