Octodet Elasticsearch MCP Server

Panoramica

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

Clona il repository.
Installa le dipendenze necessarie:

npm install

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:

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:

Definisci lo strumento in src/index.ts utilizzando il formato di registrazione degli strumenti del server MCP.
Implementa la funzionalità necessaria in src/utils/elasticsearchService.ts.
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.

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

Panoramica