Octodet Elasticsearch MCP Server

Un servidor MCP para interactuar con clústeres de Elasticsearch, que permite a aplicaciones impulsadas por LLM buscar, actualizar y gestionar datos.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Octodet Elasticsearch

Un servidor de Protocolo de Contexto de Modelo (MCP) para operaciones de Elasticsearch, que proporciona un conjunto completo de herramientas para interactuar con clústeres de Elasticsearch a través del Protocolo de Contexto de Modelo estandarizado. Este servidor permite que aplicaciones impulsadas por LLM busquen, actualicen y gestionen datos de Elasticsearch.

Características

Operaciones completas de Elasticsearch: Operaciones CRUD completas para documentos e índices
Operaciones masivas: Procesa múltiples operaciones en una sola llamada API
Actualizaciones/eliminaciones basadas en consultas: Modifica o elimina documentos según consultas
Gestión de clústeres: Monitorea salud, fragmentos y plantillas
Búsqueda avanzada: Soporte completo para consultas DSL de Elasticsearch con resaltado

Instalación

Como paquete NPM

Instala el paquete globalmente:

npm install -g @octodet/elasticsearch-mcp

O úsalo directamente con npx:

npx @octodet/elasticsearch-mcp

Desde el código fuente

Clona este repositorio
Instala las dependencias:

npm install

Compila el servidor:

npm run build

Integración con clientes MCP

Integración con VS Code

Agrega la siguiente configuración a tu archivo settings.json de VS Code para integrarte con la extensión MCP de VS Code:

"mcp.servers": {
  "elasticsearch": {
    "command": "npx",
    "args": [
      "-y", "@octodet/elasticsearch-mcp"
    ],
    "env": {
      "ES_URL": "http://localhost:9200",
      "ES_API_KEY": "your_api_key",
      "ES_VERSION": "8"
    }
  }
}

Integración con Claude Desktop

Configura en tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@octodet/elasticsearch-mcp"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

Para desarrollo local

Si estás desarrollando el servidor MCP localmente, puedes configurar los clientes para usar tu compilación local:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

Configuración

El servidor utiliza las siguientes variables de entorno para su configuración:

Variable	Descripción	Valor predeterminado
ES_URL	URL del servidor Elasticsearch	http://localhost:9200
ES_API_KEY	Clave API para autenticación
ES_USERNAME	Nombre de usuario para autenticación
ES_PASSWORD	Contraseña para autenticación
ES_CA_CERT	Ruta al certificado CA personalizado
ES_VERSION	Versión de Elasticsearch (8 o 9)	8
ES_SSL_SKIP_VERIFY	Omitir verificación SSL	false
ES_PATH_PREFIX	Prefijo de ruta para Elasticsearch

Herramientas

El servidor proporciona 16 herramientas MCP para operaciones de Elasticsearch. Cada herramienta está documentada con sus parámetros requeridos y opcionales:

1. Listar índices

Lista todos los índices de Elasticsearch disponibles con información detallada.

Parámetros:

indexPattern (opcional, cadena): Patrón para filtrar índices (por ejemplo, "logs-", "mi-índice-")

Ejemplo:

{
  "indexPattern": "logs-*"
}

2. Obtener mapeos

Obtiene los mapeos de campos para un índice específico de Elasticsearch.

Parámetros:

index (requerido, cadena): El nombre del índice del cual obtener los mapeos

Ejemplo:

{
  "index": "my-index"
}

3. Búsqueda

Realiza una búsqueda en Elasticsearch con el DSL de consulta proporcionado y resaltado.

Parámetros:

index (requerido, cadena): El índice o índices donde buscar (admite valores separados por comas)
queryBody (requerido, objeto): El cuerpo DSL de la consulta de Elasticsearch
highlight (opcional, booleano): Habilita el resaltado de resultados de búsqueda (predeterminado: true)

Ejemplo:

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "search term"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obtener salud del clúster

Obtiene información de salud sobre el clúster de Elasticsearch.

Parámetros:

Ninguno requerido

Ejemplo:

{}

5. Obtener fragmentos

Obtiene información de fragmentos para todos o índices específicos.

Parámetros:

index (opcional, cadena): Índice específico para obtener información de fragmentos. Si se omite, devuelve fragmentos de todos los índices

Ejemplo:

{
  "index": "my-index"
}

6. Agregar documento

Agrega un nuevo documento a un índice específico de Elasticsearch.

Parámetros:

index (requerido, cadena): El índice al cual agregar el documento
document (requerido, objeto): El contenido del documento a agregar
id (opcional, cadena): ID del documento. Si se omite, Elasticsearch generará uno automáticamente

Ejemplo:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "My Document",
    "content": "Document content here",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "draft"]
  }
}

7. Actualizar documento

Actualiza un documento existente en un índice específico de Elasticsearch.

Parámetros:

index (requerido, cadena): El índice que contiene el documento
id (requerido, cadena): El ID del documento a actualizar
document (requerido, objeto): El documento parcial con los campos a actualizar

Ejemplo:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Updated Document Title",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Eliminar documento

Elimina un documento de un índice específico de Elasticsearch.

Parámetros:

index (requerido, cadena): El índice que contiene el documento
id (requerido, cadena): El ID del documento a eliminar

Ejemplo:

{
  "index": "my-index",
  "id": "doc1"
}

9. Actualizar por consulta

Actualiza documentos en un índice de Elasticsearch según una consulta.

Parámetros:

index (requerido, cadena): El índice donde actualizar documentos
query (requerido, objeto): Consulta de Elasticsearch para coincidir documentos para actualización
script (requerido, objeto): Script a ejecutar para actualizar los documentos coincidentes
conflicts (opcional, cadena): Cómo manejar conflictos de versión ("abort" o "proceed", predeterminado: "abort")
refresh (opcional, booleano): Si refrescar el índice después de la operación (predeterminado: false)

Ejemplo:

{
  "index": "my-index",
  "query": {
    "term": {
      "status": "active"
    }
  },
  "script": {
    "source": "ctx._source.status = params.newStatus; ctx._source.updated_at = params.timestamp",
    "params": {
      "newStatus": "inactive",
      "timestamp": "2025-06-23T10:30:00Z"
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

10. Eliminar por consulta

Elimina documentos en un índice de Elasticsearch según una consulta.

Parámetros:

index (requerido, cadena): El índice del cual eliminar documentos
query (requerido, objeto): Consulta de Elasticsearch para coincidir documentos para eliminación
conflicts (opcional, cadena): Cómo manejar conflictos de versión ("abort" o "proceed", predeterminado: "abort")
refresh (opcional, booleano): Si refrescar el índice después de la operación (predeterminado: false)

Ejemplo:

{
  "index": "my-index",
  "query": {
    "range": {
      "created_date": {
        "lt": "2025-01-01"
      }
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

11. Operaciones masivas

Realiza múltiples operaciones de documentos en una sola llamada API para mejor rendimiento.

Parámetros:

operations (requerido, matriz): Matriz de objetos de operación, cada uno contiene:
- action (requerido, cadena): El tipo de operación ("index", "create", "update" o "delete")
- index (requerido, cadena): El índice para esta operación
- id (opcional, cadena): ID del documento (requerido para update/delete, opcional para index/create)
- document (condicional, objeto): Contenido del documento (requerido para operaciones index/create/update)

Ejemplo:

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Content here" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Updated Title" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Crear índice

Crea un nuevo índice de Elasticsearch con configuraciones y mapeos opcionales.

Parámetros:

index (requerido, cadena): El nombre del índice a crear
settings (opcional, objeto): Configuraciones del índice como número de fragmentos, réplicas, etc.
mappings (opcional, objeto): Mapeos de campos que definen cómo deben indexarse los documentos

Ejemplo:

{
  "index": "new-index",
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "standard",
          "stopwords": "_english_"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "custom_analyzer"
      },
      "created": {
        "type": "date",
        "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
      },
      "tags": {
        "type": "keyword"
      }
    }
  }
}

13. Eliminar índice

Elimina un índice de Elasticsearch permanentemente.

Parámetros:

index (requerido, cadena): El nombre del índice a eliminar

Ejemplo:

{
  "index": "my-index"
}

14. Contar documentos

Cuenta documentos en un índice, opcionalmente filtrados por una consulta.

Parámetros:

index (requerido, cadena): El índice donde contar documentos
query (opcional, objeto): Consulta de Elasticsearch para filtrar documentos para el conteo

Ejemplo:

{
  "index": "my-index",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "active" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Obtener plantillas

Obtiene plantillas de índice de Elasticsearch.

Parámetros:

name (opcional, cadena): Nombre de plantilla específica a recuperar. Si se omite, devuelve todas las plantillas

Ejemplo:

{
  "name": "logs-template"
}

16. Obtener alias

Obtiene alias de índice de Elasticsearch.

Parámetros:

name (opcional, cadena): Nombre de alias específico a recuperar. Si se omite, devuelve todos los alias

Ejemplo:

{
  "name": "logs-alias"
}

Desarrollo

Ejecución en modo de desarrollo

Ejecuta el servidor en modo de observación durante el desarrollo:

npm run dev

Implementación del protocolo

Este servidor implementa el Protocolo de Contexto de Modelo para habilitar comunicación estandarizada entre clientes LLM y Elasticsearch. Proporciona un conjunto de herramientas que pueden ser invocadas por clientes MCP para realizar diversas operaciones de Elasticsearch.

Agregar nuevas herramientas

Para agregar una nueva herramienta al servidor:

Define la herramienta en src/index.ts usando el formato de registro de herramientas del servidor MCP
Implementa la funcionalidad necesaria en src/utils/elasticsearchService.ts
Actualiza este README para documentar la nueva herramienta

Otros clientes MCP

Este servidor puede usarse con cualquier cliente compatible con MCP, incluyendo:

OpenAI's ChatGPT mediante complementos MCP
Anthropic's Claude Desktop
Claude en VS Code
Aplicaciones personalizadas que usen el SDK de MCP

Uso programático

También puedes usar el servidor programáticamente en tus aplicaciones Node.js:

import { createOctodetElasticsearchMcpServer } from "@octodet/elasticsearch-mcp";
import { CustomTransport } from "@modelcontextprotocol/sdk/server";

// Configure the Elasticsearch connection
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Create and start the server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connect to your custom transport
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP server started");
}

startServer().catch(console.error);

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.