Octodet Elasticsearch MCP-Server

Octodet Elasticsearch MCP Server

Der Octodet Elasticsearch MCP Server ist ein leistungsstarker Model Context Protocol (MCP) Server, der für eine nahtlose Interaktion mit Elasticsearch-Clustern entwickelt wurde. Er bietet eine standardisierte Möglichkeit für LLM-gestützte Anwendungen, verschiedene Operationen wie Suchen, Aktualisieren und Verwalten von Daten innerhalb von Elasticsearch durchzuführen.

Funktionen

• Vollständige Elasticsearch-Operationen: Führen Sie mühelos vollständige CRUD-Operationen auf Dokumenten und Indizes aus.
• Bulk-Operationen: Verbessern Sie die Leistung, indem Sie mehrere Operationen in einem einzigen API-Aufruf verarbeiten.
• Abfragebasierte Updates/Löschungen: Ändern oder entfernen Sie Dokumente basierend auf spezifischen Abfragen.
• Clusterverwaltung: Überwachen Sie die Gesundheit Ihres Elasticsearch-Clusters, einschließlich Shards und Vorlagen.
• Erweiterte Suche: Nutzen Sie die vollen Möglichkeiten der Elasticsearch DSL-Abfragen mit integrierter Hervorhebungsunterstützung.

Installation

Als NPM-Paket

Um den Octodet Elasticsearch MCP Server global zu installieren, führen Sie aus:

npm install -g @octodet/elasticsearch-mcp

Alternativ können Sie ihn direkt mit npx verwenden:

npx @octodet/elasticsearch-mcp

Aus dem Quellcode

1. Klonen Sie das Repository.
2. Installieren Sie die erforderlichen Abhängigkeiten:

npm install

3. Bauen Sie den Server:

npm run build

Integration mit MCP-Clients

VS Code-Integration

Um sich mit der VS Code MCP-Erweiterung zu integrieren, fügen Sie die folgende Konfiguration zu Ihrer settings.json hinzu:

"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

Für Claude Desktop konfigurieren Sie Ihre Einstellungen wie folgt:

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

Für die lokale Entwicklung

Wenn Sie den MCP-Server lokal entwickeln, konfigurieren Sie Ihre Clients so, dass sie Ihren lokalen Build verwenden:

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

Konfiguration

Der Server kann mit den folgenden Umgebungsvariablen konfiguriert werden:

Variable	Beschreibung	Standardwert
ES_URL	URL des Elasticsearch-Servers	http://localhost:9200
ES_API_KEY	API-Schlüssel zur Authentifizierung
ES_USERNAME	Benutzername zur Authentifizierung
ES_PASSWORD	Passwort zur Authentifizierung
ES_CA_CERT	Pfad zum benutzerdefinierten CA-Zertifikat
ES_VERSION	Elasticsearch-Version (8 oder 9)	8
ES_SSL_SKIP_VERIFY	SSL-Überprüfung überspringen	false
ES_PATH_PREFIX	Pfadpräfix für Elasticsearch

Werkzeuge

Der Server umfasst 16 MCP-Werkzeuge für verschiedene Elasticsearch-Operationen, die jeweils mit erforderlichen und optionalen Parametern dokumentiert sind.

1. Indizes auflisten

Rufen Sie eine Liste aller verfügbaren Elasticsearch-Indizes mit detaillierten Informationen ab.

Parameter:

• indexPattern (optional, string): Muster zum Filtern von Indizes (z. B. "logs-", "my-index-")

Beispiel:

{
  "indexPattern": "logs-*"
}

2. Mappings abrufen

Holen Sie sich die Feldzuordnungen für einen bestimmten Elasticsearch-Index.

Parameter:

• index (erforderlich, string): Der Name des Index, für den die Zuordnungen abgerufen werden sollen.

Beispiel:

{
  "index": "my-index"
}

3. Suchen

Führen Sie eine Elasticsearch-Suche mit der bereitgestellten Abfrage-DSL und Hervorhebung durch.

Parameter:

• index (erforderlich, string): Der Index oder die Indizes, in denen gesucht werden soll (unterstützt durch Kommas getrennte Werte).
• queryBody (erforderlich, object): Der Elasticsearch-Abfrage-DSL-Body.
• highlight (optional, boolean): Hervorhebung der Suchergebnisse aktivieren (Standard: true).

Beispiel:

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

4. Cluster-Gesundheit abrufen

Erhalten Sie Gesundheitsinformationen über das Elasticsearch-Cluster.

Parameter:

• Keine erforderlich.

Beispiel:

{}

5. Shards abrufen

Rufen Sie Shard-Informationen für alle oder spezifische Indizes ab.

Parameter:

• index (optional, string): Spezifischer Index, für den Shard-Informationen abgerufen werden sollen. Wenn weggelassen, werden Shards für alle Indizes zurückgegeben.

Beispiel:

{
  "index": "my-index"
}

6. Dokument hinzufügen

Fügen Sie ein neues Dokument in einen bestimmten Elasticsearch-Index ein.

Parameter:

• index (erforderlich, string): Der Index, in den das Dokument hinzugefügt werden soll.
• document (erforderlich, object): Der Inhalt des hinzuzufügenden Dokuments.
• id (optional, string): Dokument-ID. Wenn weggelassen, generiert Elasticsearch automatisch eine.

Beispiel:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Mein Dokument",
    "content": "Inhalt des Dokuments hier",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["wichtig", "entwurf"]
  }
}

7. Dokument aktualisieren

Ändern Sie ein vorhandenes Dokument in einem bestimmten Elasticsearch-Index.

Parameter:

• index (erforderlich, string): Der Index, der das Dokument enthält.
• id (erforderlich, string): Die ID des zu aktualisierenden Dokuments.
• document (erforderlich, object): Das partielle Dokument mit den zu aktualisierenden Feldern.

Beispiel:

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

8. Dokument löschen

Entfernen Sie ein Dokument aus einem bestimmten Elasticsearch-Index.

Parameter:

• index (erforderlich, string): Der Index, der das Dokument enthält.
• id (erforderlich, string): Die ID des zu löschenden Dokuments.

Beispiel:

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

9. Aktualisieren nach Abfrage

Aktualisieren Sie Dokumente in einem Elasticsearch-Index basierend auf einer Abfrage.

Parameter:

• index (erforderlich, string): Der Index, in dem Dokumente aktualisiert werden sollen.
• query (erforderlich, object): Elasticsearch-Abfrage zum Abgleichen von Dokumenten für die Aktualisierung.
• script (erforderlich, object): Skript, das zur Aktualisierung der übereinstimmenden Dokumente ausgeführt werden soll.
• conflicts (optional, string): Wie mit Versionskonflikten umgegangen werden soll ("abort" oder "proceed", Standard: "abort").
• refresh (optional, boolean): Ob der Index nach der Operation aktualisiert werden soll (Standard: false).

Beispiel:

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

10. Löschen nach Abfrage

Löschen Sie Dokumente in einem Elasticsearch-Index basierend auf einer Abfrage.

Parameter:

• index (erforderlich, string): Der Index, aus dem Dokumente gelöscht werden sollen.
• query (erforderlich, object): Elasticsearch-Abfrage zum Abgleichen von Dokumenten für die Löschung.
• conflicts (optional, string): Wie mit Versionskonflikten umgegangen werden soll ("abort" oder "proceed", Standard: "abort").
• refresh (optional, boolean): Ob der Index nach der Operation aktualisiert werden soll (Standard: false).

Beispiel:

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

11. Bulk-Operationen

Führen Sie mehrere Dokumentoperationen in einem einzigen API-Aufruf zur Verbesserung der Leistung aus.

Parameter:

• operations (erforderlich, array): Array von Operationsobjekten, die jeweils enthalten:
  • action (erforderlich, string): Der Operationstyp ("index", "create", "update" oder "delete").
  • index (erforderlich, string): Der Index für diese Operation.
  • id (optional, string): Dokument-ID (erforderlich für Update/Löschung, optional für Index/Erstellung).
  • document (bedingt, object): Dokumentinhalt (erforderlich für Index/Erstellung/Aktualisierung).

Beispiel:

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Dokument 1", "content": "Inhalt hier" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Aktualisierter Titel" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Index erstellen

Erstellen Sie einen neuen Elasticsearch-Index mit optionalen Einstellungen und Zuordnungen.

Parameter:

• index (erforderlich, string): Der Name des zu erstellenden Index.
• settings (optional, object): Indexeinstellungen wie Anzahl der Shards, Replikate usw.
• mappings (optional, object): Feldzuordnungen, die definieren, wie Dokumente indiziert werden sollen.

Beispiel:

{
  "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. Index löschen

Löschen Sie einen Elasticsearch-Index dauerhaft.

Parameter:

• index (erforderlich, string): Der Name des zu löschenden Index.

Beispiel:

{
  "index": "my-index"
}

14. Dokumente zählen

Zählen Sie Dokumente in einem Index, optional gefiltert durch eine Abfrage.

Parameter:

• index (erforderlich, string): Der Index, in dem Dokumente gezählt werden sollen.
• query (optional, object): Elasticsearch-Abfrage zum Filtern von Dokumenten für die Zählung.

Beispiel:

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

15. Vorlagen abrufen

Rufen Sie Indexvorlagen von Elasticsearch ab.

Parameter:

• name (optional, string): Spezifischer Vorlagenname zum Abrufen. Wenn weggelassen, werden alle Vorlagen zurückgegeben.

Beispiel:

{
  "name": "logs-template"
}

16. Aliase abrufen

Holen Sie sich Indexalias von Elasticsearch.

Parameter:

• name (optional, string): Spezifischer Aliasname zum Abrufen. Wenn weggelassen, werden alle Aliase zurückgegeben.

Beispiel:

{
  "name": "logs-alias"
}

Entwicklung

Im Entwicklungsmodus ausführen

Um den Server im Überwachungsmodus während der Entwicklung auszuführen, verwenden Sie:

npm run dev

Protokollimplementierung

Dieser Server implementiert das Model Context Protocol, um eine standardisierte Kommunikation zwischen LLM-Clients und Elasticsearch zu erleichtern. Er bietet eine umfassende Sammlung von Werkzeugen, die von MCP-Clients aufgerufen werden können, um verschiedene Elasticsearch-Operationen durchzuführen.

Hinzufügen neuer Werkzeuge

Um ein neues Werkzeug zum Server hinzuzufügen:

1. Definieren Sie das Werkzeug in src/index.ts unter Verwendung des Registrierungsformats des MCP-Servers.
2. Implementieren Sie die erforderliche Funktionalität in src/utils/elasticsearchService.ts.
3. Aktualisieren Sie dieses README, um das neue Werkzeug zu dokumentieren.

Andere MCP-Clients

Der Octodet Elasticsearch MCP Server kann mit jedem MCP-kompatiblen Client verwendet werden, einschließlich:

• OpenAI's ChatGPT über MCP-Plugins
• Anthropic's Claude Desktop
• Claude in VS Code
• Benutzerdefinierte Anwendungen, die das MCP SDK verwenden

Programmatische Nutzung

Sie können den Server auch programmgesteuert in Ihren Node.js-Anwendungen verwenden:

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

// Konfigurieren Sie die Elasticsearch-Verbindung
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Erstellen und starten Sie den Server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Verbinden Sie sich mit Ihrem benutzerdefinierten Transport
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP-Server gestartet");
}

startServer().catch(console.error);

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE Datei für Details.