Servidor MCP de Elasticsearch 7.x

Servidor MCP para conectarte a tu clúster de Elasticsearch directamente desde cualquier cliente MCP (como Claude Desktop, Cursor).

[!IMPORTANT] Este fork está enfocado solo a Elasticsearch 7.x. Fija el cliente @elastic/elasticsearch 7.17, cuya comprobación de producto acepta servidores anteriores a la 7.14. Para un clúster de Elasticsearch 8.x, usa el proyecto upstream @awesome-ai/elasticsearch-mcp, del que se derive este fork: el cliente 8.x no puede comunicarse con un servidor 7.x, y viceversa.

Este servidor conecta a los agentes con tus datos de Elasticsearch mediante el Model Context Protocol. Te permite interactuar con tus índices de Elasticsearch a través de conversaciones en lenguaje natural.

Resumen de funcionalidades

Las herramientas se organizan en tres conjuntos. Solo el primero está siempre expuesto; los otros dos se activan mediante una variable de entorno, de modo que un despliegue de producción pueda ofrecer diagnósticos sin ofrecer borrados. La activación ocurre en el registro: una herramienta deshabilitada no aparece nunca en tools/list, así que el modelo no puede llamarla y no consume nada en el contexto del agente.

Siempre disponibles — lectura y escritura de datos

Clúster

• elasticsearch_health: salud del clúster, opcionalmente hasta el nivel de índice.

• cluster_info: nombre del clúster, versión de Elasticsearch y variante de build.

Operaciones con índices

• list_indices: lista índices, filtrados por un comodín de Elasticsearch (log-*).

• create_index: crea un índice con configuraciones y mapeos opcionales.

• reindex: copia un índice, opcionalmente filtrado por una consulta o transformado por un script.

• get_aliases: qué aliases apuntan a qué índices.

Mapeos

• get_mappings: los campos de un índice, como rutas punteadas con sus tipos, y luego el mapeo en bruto.

• create_mapping: crea o actualiza el mapeo de un índice.

Búsqueda y datos

• search: ejecuta una búsqueda de query DSL, con resaltado inyectado en todos los campos de texto — incluidos los anidados — a menos que la consulta traiga su propio highlight.

• count: cuántos documentos coinciden, sin transferir ninguno.

• get_document: obtiene un documento por su id.

• bulk: indexa muchos documentos a la vez.

Plantillas

• create_index_template: crea o actualiza una plantilla de índice componible.

• get_index_template: lee plantillas de índice.

Tareas

• get_task: avance de una tarea de larga duración, como la que devuelve reindex.

ES_ADMIN_TOOLS=true — diagnóstico (solo lectura)

Estas herramientas solo leen, así que es seguro activarlas en producción — y ese es su propósito: un agente puede entonces explicar por qué un índice no está sano sin que nadie inicie sesión en el clúster.

• explain_allocation: por qué un shard no está asignado, con la decisión de cada asignador.

• list_shards: estado a nivel de shard, empezando por las copias que no están STARTED.

• list_nodes: heap, CPU, carga y presión de disco por nodo.

• get_index_stats: contadores por índice — tamaño, segmentos, indexación, búsqueda, merges.

• get_index_settings: la configuración de un índice (refresh_interval, réplicas, bloques de solo lectura).

• get_cluster_settings: configuración del clúster que fue sobrescrita en tiempo de ejecución.

• list_tasks: qué está ejecutando el clúster actualmente.

ES_ALLOW_DESTRUCTIVE=true — irreversible

Está pensado para un entorno de staging y está desactivado por defecto, así que la producción no puede alcanzar estas herramientas en absoluto.

• delete_index: elimina un índice y sus datos.

• delete_document: elimina un documento por su id.

• delete_by_query: elimina todos los documentos que coinciden con una consulta — asincrónico, devuelve un id de tarea y el borrado continúa en segundo plano.

• delete_index_template: elimina una plantilla de índice.

Incluso con la bandera activada, estas herramientas rechazan un comodín, una lista separada por comas, * y _all: actúan sobre un solo índice con nombre a la vez. Un modelo que confunda logs-* con un índice único recibe un rechazo en lugar de un clúster vacío.

Cómo funciona

1. El cliente MCP analiza tu solicitud y determina qué operaciones de Elasticsearch son necesarias.

2. El servidor MCP lleva a cabo estas operaciones (listar índices, obtener mapeos, realizar búsquedas).

3. El cliente MCP procesa los resultados y los presenta en un formato fácil de usar.

Related MCP server: Elasticsearch 7.x MCP Server

Primeros pasos

Requisitos previos

• Una instancia de Elasticsearch 7.x (probada con 7.8; el cliente 7.17 es compatible desde 6.8 hasta 7.x).

• Credenciales de Elasticsearch: una API key, o un nombre de usuario y una contraseña.

• Un cliente MCP: Claude Code, Claude Desktop, Codex, Cursor, o cualquier otra cosa que hable MCP por stdio.

Autentícate en GitHub Packages, una vez

[!IMPORTANT] Este paquete se publica en GitHub Packages, no en npmjs.com, y GitHub Packages requiere un token incluso para paquetes públicos. Hasta que añadas uno, cada instalación de abajo fallará con un 401. Ponlo en tu ~/.npmrc de nivel de usuario:

@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN es un personal access token con el ámbito read:packages.

Guárdalo en tu propio ~/.npmrc, y no en un archivo de proyecto: un token enviado a un repositorio es un token filtrado, y algunos gestores de paquetes se niegan a leerlo desde ahí.

Conéctalo a tu cliente

Cada ejemplo de abajo define ES_HOST y ES_API_KEY. Cambia ES_API_KEY por ES_USERNAME/ES_PASSWORD para autenticación básica, añade ES_ADMIN_TOOLS=true para obtener las herramientas de diagnóstico, y establece ES_INSTANCE_LABEL cuando declares más de una instancia; consulta Opciones de configuración.

claude mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  --env ES_ADMIN_TOOLS=true \
  -- npx -y @agrica/elasticsearch7-mcp

Después, /mcp en una sesión muestra el servidor y sus herramientas.

Dos detalles que son fáciles de equivocar:

• Todo lo que está después de -- es el comando que ejecuta el servidor; sin él, Claude Code intentaría interpretar -y como una de sus propias opciones.

• No pongas el nombre del servidor justo después de --env: la CLI lo lee como otro par KEY=value y lo rechaza. Arriba, el nombre va primero, que es por lo que funciona.

El servidor se agrega en el ámbito local, por lo que solo se carga en el proyecto actual. Añade --scope user para tenerlo en todas partes, o --scope project para escribirlo en .mcp.json y compartirlo con tu equipo: ten en cuenta que un .mcp.json enviado al repositorio contendría tu API key, así que prefiere el ámbito de usuario para las credenciales.

Edita claude_desktop_config.json: Settings > Developer > Edit Config lo abre, o encuéntralo en %APPDATA%\Claude\ en Windows y en ~/Library/Application Support/Claude/ en macOS:

{
  "mcpServers": {
    "elasticsearch7": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://your-cluster:9200",
        "ES_API_KEY": "your-api-key",
        "ES_ADMIN_TOOLS": "true"
      }
    }
  }
}

Reinicia Claude Desktop después; solo lee ese archivo al inicio.

codex mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  -- npx -y @agrica/elasticsearch7-mcp

O escríbelo a mano en ~/.codex/config.toml. Ten en cuenta que Codex escribe la tabla como mcp_servers, con un guion bajo, y que el entorno va en su propia sub-tabla, en lugar de en línea:

[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]

[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"

/mcp dentro de Codex confirma que el servidor está cargado.

El servidor es un servidor MCP de stdio normal, así que funciona con todo lo que es lista de clientes MCP. Necesita tres cosas: el comando npx, los argumentos -y @agrica/elasticsearch7-mcp y las variables ES_* en su entorno. Nunca escucha en un puerto y no escribe nada más que el protocolo MCP por stdout: los diagnósticos van a stderr.

Opciones de configuración

The Elasticsearch MCP Server admite opciones de configuración para conectarse a tu Elasticsearch:

[!NOTE] Debes proporcionar una API key o tanto nombre de usuario como una contraseña para la autenticación.

[!WARNING] ES_ADMIN_TOOLS y ES_ALLOW_DESTRUCTIVE no tienen un alias heredado sin prefijo, a diferencia de las variables de conexión anteriores. Esto es deliberado: un ADMIN_TOOLS o ALLOW_DESTRUCTIVE suelto en el entorno es demasiado fácil de activar por accidente para una característica que decide si los borrados son accesibles.

Ambas aceptan true o 1; cualquier otra cosa, incluida una variable sin definir, significa que está desactivado.

Tamaño del resultado

Un resultado de herramienta está limitado a 32 KB (ES_MAX_RESULT_BYTES). Esto importa en un clúster de registros: antes del límite, una sola llamada a list_shards sobre un año de índices diarios devolvía 385 KB (alrededor de 96 000 tokens) en una sola respuesta, más de lo que la mayoría de las sesiones pueden retener.

Cuando un resultado se recorta, el propio resultado lo dice, indica cuánto se recortó y explica cómo hacer una pregunta más pequeña. Tres herramientas adaptan sus respuestas:

• list_indices y list_shards devuelven un resumen legible; las mismas filas con texto se obtienen con verbose.

• search limita el size a 100 por llamada y te indica el from con el que paginar.

• get_mappings enumera primero los campos y luego el mapeo en bruto, de modo que un índice con mil campos sigue respondiendo a la pregunta que se hizo.

Cuatro herramientas — list_indices, list_shards, get_index_settings y get_mappings — también devuelven su respuesta como salida estructurada y tipada, de modo que un cliente pueda leer las filas en lugar de interpretar el texto. Se compone con el espacio de la respuesta legible y devuelve returned contra total, para que un listado parcial se vea como número.

Ejecuta pnpm run measure sobre la versión construida para ver las cifras actuales de tu propia configuración.

Etiquetado de varias instancias

La mayoría de las configuraciones declaran este servidor más de una vez — una entrada por clúster. Por lo demás, las entradas son idénticas, así que un cliente muestra dos servidores con el mismo nombre y nada que los distinga. ES_INSTANCE_LABEL se convierte en el título visible del servidor, y es el lugar natural para decir qué entorno alcanza cada entrada:

{
  "mcpServers": {
    "es7-prod": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-prod:9200",
        "ES_API_KEY": "prod-key",
        "ES_INSTANCE_LABEL": "production",
        "ES_ADMIN_TOOLS": "true"
      }
    },
    "es7-staging": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-staging:9200",
        "ES_API_KEY": "staging-key",
        "ES_INSTANCE_LABEL": "staging",
        "ES_ADMIN_TOOLS": "true",
        "ES_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

Ese par es la forma prevista: diagnósticos en ambos, borrados solo en staging. Producción conserva las herramientas que explican un índice en mal estado y nunca expone una que pueda eliminar datos: el modelo no puede llamar a lo que nunca se registró.

La etiqueta también se imprime en stderr al inicio, que es donde hay que mirar cuando un cliente informa de una conexión pero no puedes saber qué clúster respondió.

Configuración de múltiples URLs

Puedes configurar varios nodos de Elasticsearch para alta disponibilidad y equilibrio de carga:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agrica/elasticsearch7-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

El cliente gestionará automáticamente la conmutación por error y el equilibrio de carga entre los nodos configurados.

Ejecución con Docker

Cada versión publica una imagen multiarquitectura (linux/amd64, linux/arm64) en el Registro de Contenedores de GitHub:

docker pull ghcr.io/agrica/elasticsearch7-mcp:latest

El servidor habla mediante stdio, así que el contenedor necesita un stdin interactivo y ningún puerto publicado. En un cliente MCP:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_HOST",
        "-e", "ES_API_KEY",
        "ghcr.io/agrica/elasticsearch7-mcp:latest"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

[!NOTE] Al igual que el paquete npm, la imagen vive en GitHub Packages: descargarla requiere un token con el ámbito read:packages, aunque el repositorio sea público.

La imagen no necesita ningún puerto publicado ni volumen: habla mediante stdio y el cliente MCP es dueño de su stdin y su stdout.

Consultas de ejemplo

[!TIP] Aquí tienes algunas consultas en lenguaje natural que puedes probar con tu cliente MCP.

Gestión del clúster

• "¿Cuál es el estado de salud de mi clúster de Elasticsearch?"

• "¿Cuántos nodos activos hay en mi clúster?"

Operaciones con índices

• "¿Qué índices tengo en mi clúster de Elasticsearch?"

• "Crea un nuevo índice llamado 'users' con 3 shards y 1 réplica."

• "Reindexa los datos de 'old_index' a 'new_index'."

Gestión de mappings

• "Muéstrame los mapeos de campos del índice 'products'."

• "Añade un campo de tipo keyword llamado 'tags' al índice 'products'."

Operaciones de búsqueda y datos

• "Busca todos los pedidos de más de 500 dólares del mes pasado."

• "¿Qué productos recibieron la mayor cantidad de reseñas de 5 estrellas?"

• "Importa en bloque estos registros de clientes al índice 'customers'."

Gestión de plantillas

• "Crea una plantilla de índice para logs con el patrón 'logs-*'."

• "Muéstrame todas mis plantillas de índice."

Diagnósticos (requiere ES_ADMIN_TOOLS=true)

• "El índice 'logs-2026' está en amarillo: ¿por qué sus shards están sin asignar?"

• "¿Está algún nodo cerca del umbral de llenado de disco?"

• "¿Cuál de mis índices es el más grande y qué parte son documentos eliminados?"

• "¿Alguien ha desactivado la asignación de shards en este clúster?"

• "¿Sigue ejecutándose una reindexación?"

Destructivas (requiere ES_ALLOW_DESTRUCTIVE=true)

• "Elimina el índice 'smoke-test-source'."

• "Elimina todos los documentos anteriores a 2024 de 'logs-archive'."

Solución de problemas

¿Has encontrado un error o quieres una herramienta que no está? Abre un issue en el repositorio de GitHub. Para trabajar en el código, empieza por CONTRIBUTING.md.