Servidor MCP de Elasticsearch Octodet

Creado por

Octodet•Jun 25, 2025

Un servidor MCP de Elasticsearch completo

Resumen

Servidor MCP de Elasticsearch Octodet

El servidor MCP de Elasticsearch Octodet es un potente servidor del Protocolo de Contexto de Modelo (MCP) diseñado para una interacción fluida con clústeres de Elasticsearch. Proporciona una forma estandarizada para que las aplicaciones impulsadas por LLM realicen diversas operaciones como buscar, actualizar y gestionar datos dentro de Elasticsearch.

Características

Operaciones completas de Elasticsearch: Ejecuta operaciones completas de CRUD en documentos e índices sin esfuerzo.
Operaciones en bloque: Mejora el rendimiento procesando múltiples operaciones en una sola llamada a la API.
Actualizaciones/Borrados basados en consultas: Modifica o elimina documentos en función de consultas específicas.
Gestión de clústeres: Monitorea la salud de tu clúster de Elasticsearch, incluidos fragmentos y plantillas.
Búsqueda avanzada: Utiliza todas las capacidades de las consultas DSL de Elasticsearch con soporte de resaltado incorporado.

Cómo instalar

Como paquete NPM

Para instalar el servidor MCP de Elasticsearch Octodet globalmente, ejecuta:

npm install -g @octodet/elasticsearch-mcp

Alternativamente, puedes usarlo directamente con npx:

npx @octodet/elasticsearch-mcp

Desde el código fuente

Clona el repositorio.
Instala las dependencias necesarias:

npm install

Construye el servidor:

npm run build

Integración con clientes MCP

Integración con VS Code

Para integrar con la extensión MCP de VS Code, agrega la siguiente configuración a tu settings.json:

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

Integración con Claude Desktop

Para Claude Desktop, configura tus ajustes de la siguiente manera:

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

Para desarrollo local

Si estás desarrollando el servidor MCP localmente, configura tus clientes para usar tu construcción local:

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

Configuración

El servidor se puede configurar utilizando las siguientes variables de entorno:

Variable	Descripción	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 incluye 16 herramientas MCP para diversas operaciones de Elasticsearch, cada una documentada con parámetros requeridos y opcionales.

1. Listar Índices

Recupera una lista de 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

Obtén los mapeos de campo para un índice específico de Elasticsearch.

Parámetros:

index (requerido, cadena): El nombre del índice para recuperar mapeos.

Ejemplo:

{
  "index": "mi-índice"
}

3. Buscar

Realiza una búsqueda en Elasticsearch utilizando la consulta DSL proporcionada y resaltado.

Parámetros:

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

Ejemplo:

{
  "index": "mi-índice",
  "queryBody": {
    "query": {
      "match": {
        "content": "término de búsqueda"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obtener Salud del Clúster

Obtén información sobre la salud del clúster de Elasticsearch.

Parámetros:

Ninguno requerido.

Ejemplo:

{}

5. Obtener Fragmentos

Recupera información sobre fragmentos para todos o índices específicos.

Parámetros:

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

Ejemplo:

{
  "index": "mi-índice"
}

6. Agregar Documento

Inserta un nuevo documento en un índice específico de Elasticsearch.

Parámetros:

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

Ejemplo:

{
  "index": "mi-índice",
  "id": "doc1",
  "document": {
    "title": "Mi Documento",
    "content": "Contenido del documento aquí",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["importante", "borrador"]
  }
}

7. Actualizar Documento

Modifica 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 campos a actualizar.

Ejemplo:

{
  "index": "mi-índice",
  "id": "doc1",
  "document": {
    "title": "Título del Documento Actualizado",
    "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": "mi-índice",
  "id": "doc1"
}

9. Actualizar por Consulta

Actualiza documentos en un índice de Elasticsearch basado en una consulta.

Parámetros:

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

Ejemplo:

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

10. Eliminar por Consulta

Elimina documentos en un índice de Elasticsearch basado en una consulta.

Parámetros:

index (requerido, cadena): El índice para 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 se debe refrescar el índice después de la operación (predeterminado: false).

Ejemplo:

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

11. Operaciones en Bloque

Ejecuta múltiples operaciones de documentos en una sola llamada a la API para mejorar el rendimiento.

Parámetros:

operations (requerido, array): Array de objetos de operación, cada uno conteniendo:
- 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 actualizar/eliminar, opcional para indexar/crear).
- document (condicional, objeto): Contenido del documento (requerido para operaciones de indexar/crear/actualizar).

Ejemplo:

{
  "operations": [
    {
      "action": "index",
      "index": "mi-índice",
      "id": "doc1",
      "document": { "title": "Documento 1", "content": "Contenido aquí" }
    },
    {
      "action": "update",
      "index": "mi-índice",
      "id": "doc2",
      "document": { "title": "Título Actualizado" }
    },
    {
      "action": "delete",
      "index": "mi-índice",
      "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 campo que definen cómo se deben indexar los documentos.

Ejemplo:

{
  "index": "nuevo-índice",
  "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 permanentemente un índice de Elasticsearch.

Parámetros:

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

Ejemplo:

{
  "index": "mi-índice"
}

14. Contar Documentos

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

Parámetros:

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

Ejemplo:

{
  "index": "mi-índice",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "activo" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Obtener Plantillas

Recupera plantillas de índice de Elasticsearch.

Parámetros:

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

Ejemplo:

{
  "name": "plantilla-logs"
}

16. Obtener Alias

Obtiene alias de índice de Elasticsearch.

Parámetros:

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

Ejemplo:

{
  "name": "alias-logs"
}

Desarrollo

Ejecutar en Modo de Desarrollo

Para ejecutar el servidor en modo de vigilancia durante el desarrollo, usa:

npm run dev

Implementación del Protocolo

Este servidor implementa el Protocolo de Contexto de Modelo para facilitar la comunicación estandarizada entre clientes LLM y Elasticsearch. Proporciona un conjunto completo 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 utilizando 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

El servidor MCP de Elasticsearch Octodet se puede utilizar con cualquier cliente compatible con MCP, incluidos:

ChatGPT de OpenAI a través de plugins MCP
Claude Desktop de Anthropic
Claude en VS Code
Aplicaciones personalizadas utilizando el SDK de MCP

Uso Programático

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

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

// Configura la conexión a Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "tu_api_key",
  version: "8",
};

// Crea y comienza el servidor
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Conéctate a tu transporte personalizado
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Servidor MCP de Elasticsearch iniciado");
}

startServer().catch(console.error);

Licencia

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

Detalle

Octodet Elasticsearch MCP Server

A Model Context Protocol (MCP) server for Elasticsearch operations, providing a comprehensive set of tools for interacting with Elasticsearch clusters through the standardized Model Context Protocol. This server enables LLM-powered applications to search, update, and manage Elasticsearch data.

Features

Complete Elasticsearch Operations: Full CRUD operations for documents and indices
Bulk Operations: Process multiple operations in a single API call
Query-Based Updates/Deletes: Modify or remove documents based on queries
Cluster Management: Monitor health, shards, and templates
Advanced Search: Full support for Elasticsearch DSL queries with highlighting

Installation

As an NPM Package

Install the package globally:

npm install -g @octodet/elasticsearch-mcp

Or use it directly with npx:

npx @octodet/elasticsearch-mcp

From Source

Clone this repository
Install dependencies:

npm install

Build the server:

npm run build

Integration with MCP Clients

VS Code Integration

Add the following configuration to your VS Code settings.json to integrate with the VS Code MCP extension:

"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"
    }
  }
}

Claude Desktop Integration

Configure in your Claude Desktop configuration file:

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

For Local Development

If you're developing the MCP server locally, you can configure the clients to use your local build:

{
  "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"
      }
    }
  }
}

Configuration

The server uses the following environment variables for configuration:

Tools

The server provides 16 MCP tools for Elasticsearch operations. Each tool is documented with its required and optional parameters:

1. List Indices

List all available Elasticsearch indices with detailed information.

Parameters:

indexPattern (optional, string): Pattern to filter indices (e.g., "logs-", "my-index-")

Example:

{
  "indexPattern": "logs-*"
}

2. Get Mappings

Get field mappings for a specific Elasticsearch index.

Parameters:

index (required, string): The name of the index to get mappings for

Example:

{
  "index": "my-index"
}

3. Search

Perform an Elasticsearch search with the provided query DSL and highlighting.

Parameters:

index (required, string): The index or indices to search in (supports comma-separated values)
queryBody (required, object): The Elasticsearch query DSL body
highlight (optional, boolean): Enable search result highlighting (default: true)

Example:

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

4. Get Cluster Health

Get health information about the Elasticsearch cluster.

Parameters:

None required

Example:

{}

5. Get Shards

Get shard information for all or specific indices.

Parameters:

index (optional, string): Specific index to get shard information for. If omitted, returns shards for all indices

Example:

{
  "index": "my-index"
}

6. Add Document

Add a new document to a specific Elasticsearch index.

Parameters:

index (required, string): The index to add the document to
document (required, object): The document content to add
id (optional, string): Document ID. If omitted, Elasticsearch will generate one automatically

Example:

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

7. Update Document

Update an existing document in a specific Elasticsearch index.

Parameters:

index (required, string): The index containing the document
id (required, string): The ID of the document to update
document (required, object): The partial document with fields to update

Example:

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

8. Delete Document

Delete a document from a specific Elasticsearch index.

Parameters:

index (required, string): The index containing the document
id (required, string): The ID of the document to delete

Example:

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

9. Update By Query

Update documents in an Elasticsearch index based on a query.

Parameters:

index (required, string): The index to update documents in
query (required, object): Elasticsearch query to match documents for update
script (required, object): Script to execute for updating matched documents
conflicts (optional, string): How to handle version conflicts ("abort" or "proceed", default: "abort")
refresh (optional, boolean): Whether to refresh the index after the operation (default: false)

Example:

{
  "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. Delete By Query

Delete documents in an Elasticsearch index based on a query.

Parameters:

index (required, string): The index to delete documents from
query (required, object): Elasticsearch query to match documents for deletion
conflicts (optional, string): How to handle version conflicts ("abort" or "proceed", default: "abort")
refresh (optional, boolean): Whether to refresh the index after the operation (default: false)

Example:

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

11. Bulk Operations

Perform multiple document operations in a single API call for better performance.

Parameters:

operations (required, array): Array of operation objects, each containing:
- action (required, string): The operation type ("index", "create", "update", or "delete")
- index (required, string): The index for this operation
- id (optional, string): Document ID (required for update/delete, optional for index/create)
- document (conditional, object): Document content (required for index/create/update operations)

Example:

{
  "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. Create Index

Create a new Elasticsearch index with optional settings and mappings.

Parameters:

index (required, string): The name of the index to create
settings (optional, object): Index settings like number of shards, replicas, etc.
mappings (optional, object): Field mappings defining how documents should be indexed

Example:

{
  "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. Delete Index

Delete an Elasticsearch index permanently.

Parameters:

index (required, string): The name of the index to delete

Example:

{
  "index": "my-index"
}

14. Count Documents

Count documents in an index, optionally filtered by a query.

Parameters:

index (required, string): The index to count documents in
query (optional, object): Elasticsearch query to filter documents for counting

Example:

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

15. Get Templates

Get index templates from Elasticsearch.

Parameters:

name (optional, string): Specific template name to retrieve. If omitted, returns all templates

Example:

{
  "name": "logs-template"
}

16. Get Aliases

Get index aliases from Elasticsearch.

Parameters:

name (optional, string): Specific alias name to retrieve. If omitted, returns all aliases

Example:

{
  "name": "logs-alias"
}

Development

Running in Development Mode

Run the server in watch mode during development:

npm run dev

Protocol Implementation

This server implements the Model Context Protocol to enable standardized communication between LLM clients and Elasticsearch. It provides a set of tools that can be invoked by MCP clients to perform various Elasticsearch operations.

Adding New Tools

To add a new tool to the server:

Define the tool in src/index.ts using the MCP server's tool registration format
Implement the necessary functionality in src/utils/elasticsearchService.ts
Update this README to document the new tool

Other MCP Clients

This server can be used with any MCP-compatible client, including:

OpenAI's ChatGPT via MCP plugins
Anthropic's Claude Desktop
Claude in VS Code
Custom applications using the MCP SDK

Programmatic Usage

You can also use the server programmatically in your Node.js applications:

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);

License

This project is licensed under the MIT License - see the LICENSE file for details.

Configuración del Servidor

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

Información del Proyecto

Autor

Octodet