Octodet Elasticsearch MCP Server

Octodet Elasticsearch MCP Server

Il server Octodet Elasticsearch MCP è un potente server del Protocollo di Contesto del Modello (MCP) progettato per un'interazione senza soluzione di continuità con i cluster Elasticsearch. Fornisce un modo standardizzato per le applicazioni alimentate da LLM di eseguire varie operazioni come ricerca, aggiornamento e gestione dei dati all'interno di Elasticsearch.

Caratteristiche

• Operazioni complete su Elasticsearch: Esegui operazioni CRUD complete su documenti e indici senza sforzo.
• Operazioni in blocco: Migliora le prestazioni elaborando più operazioni in una singola chiamata API.
• Aggiornamenti/Cancellazioni basati su query: Modifica o rimuovi documenti in base a query specifiche.
• Gestione del cluster: Monitora la salute del tuo cluster Elasticsearch, inclusi shard e modelli.
• Ricerca avanzata: Utilizza tutte le capacità delle query DSL di Elasticsearch con supporto integrato per l'evidenziazione.

Come Installare

Come Pacchetto NPM

Per installare il server Octodet Elasticsearch MCP globalmente, esegui:

npm install -g @octodet/elasticsearch-mcp

In alternativa, puoi usarlo direttamente con npx:

npx @octodet/elasticsearch-mcp

Da Sorgente

1. Clona il repository.
2. Installa le dipendenze necessarie:

npm install

3. Compila il server:

npm run build

Integrazione con Client MCP

Integrazione con VS Code

Per integrare con l'estensione MCP di VS Code, aggiungi la seguente configurazione al tuo settings.json:

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

Integrazione con Claude Desktop

Per Claude Desktop, configura le tue impostazioni come segue:

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

Per Sviluppo Locale

Se stai sviluppando il server MCP localmente, configura i tuoi client per utilizzare la tua build locale:

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

Configurazione

Il server può essere configurato utilizzando le seguenti variabili d'ambiente:

| Variabile | Descrizione | Predefinito | | | | | | ES_URL | URL del server Elasticsearch | http://localhost:9200 | | ES_API_KEY | Chiave API per l'autenticazione | | | ES_USERNAME | Nome utente per l'autenticazione| | | ES_PASSWORD | Password per l'autenticazione | | | ES_CA_CERT | Percorso al certificato CA personalizzato | | | ES_VERSION | Versione di Elasticsearch (8 o 9)| 8 | | ES_SSL_SKIP_VERIFY | Salta la verifica SSL | false | | ES_PATH_PREFIX | Prefisso del percorso per Elasticsearch | |

Strumenti

Il server include 16 strumenti MCP per varie operazioni su Elasticsearch, ciascuno documentato con parametri richiesti e opzionali.

1. Elenca Indici

Recupera un elenco di tutti gli indici Elasticsearch disponibili con informazioni dettagliate.

Parametri:

• indexPattern (opzionale, stringa): Modello per filtrare gli indici (es. "logs-", "my-index-")

Esempio:

{
  "indexPattern": "logs-*"
}

2. Ottieni Mappature

Recupera le mappature dei campi per un indice Elasticsearch specifico.

Parametri:

• index (richiesto, stringa): Il nome dell'indice per cui recuperare le mappature.

Esempio:

{
  "index": "my-index"
}

3. Ricerca

Esegui una ricerca Elasticsearch utilizzando la query DSL fornita e l'evidenziazione.

Parametri:

• index (richiesto, stringa): L'indice o gli indici su cui cercare (supporta valori separati da virgola).
• queryBody (richiesto, oggetto): Il corpo della query DSL di Elasticsearch.
• highlight (opzionale, booleano): Abilita l'evidenziazione per i risultati della ricerca (predefinito: true).

Esempio:

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

4. Ottieni Salute del Cluster

Ottieni informazioni sulla salute del cluster Elasticsearch.

Parametri:

• Nessuno richiesto.

Esempio:

{}

5. Ottieni Shard

Recupera informazioni sugli shard per tutti o specifici indici.

Parametri:

• index (opzionale, stringa): Indice specifico per ottenere informazioni sugli shard. Se omesso, restituisce gli shard per tutti gli indici.

Esempio:

{
  "index": "my-index"
}

6. Aggiungi Documento

Inserisci un nuovo documento in un indice Elasticsearch specifico.

Parametri:

• index (richiesto, stringa): L'indice a cui verrà aggiunto il documento.
• document (richiesto, oggetto): Il contenuto del documento da aggiungere.
• id (opzionale, stringa): ID del documento. Se omesso, Elasticsearch ne genera uno automaticamente.

Esempio:

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

7. Aggiorna Documento

Modifica un documento esistente in un indice Elasticsearch specifico.

Parametri:

• index (richiesto, stringa): L'indice contenente il documento.
• id (richiesto, stringa): L'ID del documento da aggiornare.
• document (richiesto, oggetto): Il documento parziale con i campi da aggiornare.

Esempio:

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

8. Elimina Documento

Rimuovi un documento da un indice Elasticsearch specifico.

Parametri:

• index (richiesto, stringa): L'indice contenente il documento.
• id (richiesto, stringa): L'ID del documento da eliminare.

Esempio:

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

9. Aggiorna per Query

Aggiorna documenti in un indice Elasticsearch in base a una query.

Parametri:

• index (richiesto, stringa): L'indice in cui aggiornare i documenti.
• query (richiesto, oggetto): Query Elasticsearch per abbinare i documenti da aggiornare.
• script (richiesto, oggetto): Script da eseguire per aggiornare i documenti abbinati.
• conflicts (opzionale, stringa): Come gestire i conflitti di versione ("abort" o "proceed", predefinito: "abort").
• refresh (opzionale, booleano): Se aggiornare l'indice dopo l'operazione (predefinito: false).

Esempio:

{
  "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. Elimina per Query

Elimina documenti in un indice Elasticsearch in base a una query.

Parametri:

• index (richiesto, stringa): L'indice da cui eliminare i documenti.
• query (richiesto, oggetto): Query Elasticsearch per abbinare i documenti da eliminare.
• conflicts (opzionale, stringa): Come gestire i conflitti di versione ("abort" o "proceed", predefinito: "abort").
• refresh (opzionale, booleano): Se aggiornare l'indice dopo l'operazione (predefinito: false).

Esempio:

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

11. Operazioni in Blocco

Esegui più operazioni su documenti in una singola chiamata API per migliorare le prestazioni.

Parametri:

• operations (richiesto, array): Array di oggetti operazione, ciascuno contenente:
  • action (richiesto, stringa): Il tipo di operazione ("index", "create", "update" o "delete").
  • index (richiesto, stringa): L'indice per questa operazione.
  • id (opzionale, stringa): ID del documento (richiesto per aggiornamento/eliminazione, opzionale per indicizzazione/creazione).
  • document (condizionale, oggetto): Contenuto del documento (richiesto per indicizzazione/creazione/aggiornamento).

Esempio:

{
  "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. Crea Indice

Crea un nuovo indice Elasticsearch con impostazioni e mappature opzionali.

Parametri:

• index (richiesto, stringa): Il nome dell'indice da creare.
• settings (opzionale, oggetto): Impostazioni dell'indice come numero di shard, repliche, ecc.
• mappings (opzionale, oggetto): Mappature dei campi che definiscono come i documenti devono essere indicizzati.

Esempio:

{
  "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. Elimina Indice

Elimina permanentemente un indice Elasticsearch.

Parametri:

• index (richiesto, stringa): Il nome dell'indice da eliminare.

Esempio:

{
  "index": "my-index"
}

14. Conta Documenti

Conta i documenti in un indice, eventualmente filtrati da una query.

Parametri:

• index (richiesto, stringa): L'indice in cui contare i documenti.
• query (opzionale, oggetto): Query Elasticsearch per filtrare i documenti da contare.

Esempio:

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

15. Ottieni Modelli

Recupera i modelli di indice da Elasticsearch.

Parametri:

• name (opzionale, stringa): Nome specifico del modello da recuperare. Se omesso, restituisce tutti i modelli.

Esempio:

{
  "name": "logs-template"
}

16. Ottieni Alias

Recupera gli alias degli indici da Elasticsearch.

Parametri:

• name (opzionale, stringa): Nome specifico dell'alias da recuperare. Se omesso, restituisce tutti gli alias.

Esempio:

{
  "name": "logs-alias"
}

Sviluppo

Esecuzione in Modalità Sviluppo

Per eseguire il server in modalità watch durante lo sviluppo, usa:

npm run dev

Implementazione del Protocollo

Questo server implementa il Protocollo di Contesto del Modello per facilitare la comunicazione standardizzata tra client LLM e Elasticsearch. Fornisce un insieme completo di strumenti che possono essere invocati dai client MCP per eseguire varie operazioni su Elasticsearch.

Aggiunta di Nuovi Strumenti

Per aggiungere un nuovo strumento al server:

1. Definisci lo strumento in src/index.ts utilizzando il formato di registrazione degli strumenti del server MCP.
2. Implementa la funzionalità necessaria in src/utils/elasticsearchService.ts.
3. Aggiorna questo README per documentare il nuovo strumento.

Altri Client MCP

Il server Octodet Elasticsearch MCP può essere utilizzato con qualsiasi client compatibile con MCP, inclusi:

• ChatGPT di OpenAI tramite plugin MCP
• Claude Desktop di Anthropic
• Claude in VS Code
• Applicazioni personalizzate utilizzando l'SDK MCP

Utilizzo Programmatico

Puoi anche utilizzare il server in modo programmatico nelle tue applicazioni Node.js:

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

// Configura la connessione a Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Crea e avvia il server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connetti al tuo trasporto personalizzato
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Server MCP Elasticsearch avviato");
}

startServer().catch(console.error);

Licenza

Questo progetto è concesso in licenza sotto la Licenza MIT - consulta il file LICENSE per i dettagli.

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

1. Clone this repository
2. Install dependencies:

npm install

3. 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:

| Variable | Description | Default | | | | | | ES_URL | Elasticsearch server URL | http://localhost:9200 | | ES_API_KEY | API key for authentication | | | ES_USERNAME | Username for authentication | | | ES_PASSWORD | Password for authentication | | | ES_CA_CERT | Path to custom CA certificate | | | ES_VERSION | Elasticsearch version (8 or 9) | 8 | | ES_SSL_SKIP_VERIFY | Skip SSL verification | false | | ES_PATH_PREFIX | Path prefix for Elasticsearch | |

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:

1. Define the tool in src/index.ts using the MCP server's tool registration format
2. Implement the necessary functionality in src/utils/elasticsearchService.ts
3. 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.