Elasticsearch 7.x MCP Server

MCP-Server, der eine direkte Verbindung von jedem MCP-Client (wie Claude Desktop, Cursor) zu deinem Elasticsearch-Cluster herstellt.

[!IMPORTANT] Dieser Fork ist ausschließlich auf Elasticsearch 7.x ausgelegt. Er legt den @elastic/elasticsearch Client in der Version 7.17 fest, dessen Produktprüfung Server älter als 7.14 akzptiert. Für einen Elasticsearch-8.x-Cluster verwende das übergeordnete Projekt @awesome-ai/elasticsearch-mcp, von dem deser Fork abgeleitet ist – der 8.x-Client kann nicht mit einem 7.x-Server sprechen und umgekehrt.

Deser Server verbindet Agents über dass Model Context Protocol mit deinen Elasticsearch-Daten. Du kannst auf diese Weise über of einen natürliche Sprache mit deinen Elasticsearch-Indizes interagieren.

Funktionsübersicht

Die Tools bestehen aus drrei Gruppen. Die erste Group ist imer immer verfügbar; die anderen beiden werden über eine Umgebungsvariable aktivert, so dass eine Produktions-Bereitselung Diagnoswerkeuge anbietet, ohne Löschvorgänge zu exponieren. Die Freischaltung erfolgt bei der Registierung: Ein depaktiviertes Tool erscheint nie in tools.ist, sodass das Modell es nicht aufrufen kann und es den Kontext des Agents nichts kostet.

Immer verfügbar – Daten lesen und schreiben

Cluster

• elasticsearch_health: Cluster-Gesundheit, optional bis auf sie auf Index-Ebene

• cluster_info: Clustername, Elasticsearch-Version und Build-Variante

Index-Operationen

• list_indices: Indizes auflisten, gefiltert per Elasticsearch-Wildcard (log-*)

• create_index: Einen Index mit optionalen Einstellungen und Mappings erstellen

• reindex: Einen Index kopieren, optional gefiltert per Abfrage oder ejene Daten transformiert per Skript

• get_aliases: Auflistung, welche Aliase auf welche Indizes zeigen

Mappings

• get_mappings: Die Felder eines Index als Punktpfade samt Typen, dann das rohe Mapping

• create_mapping: Mapping eines Index erstellen oder aktualisieren

Suche und Daten

• search: Eine Query-DSL-Suche ausführen, mit hervorgehobem Text über jedes Textfelder – einschließlich verschachtelter – außerdem die Abfrage kein eigenes highlight mitbringt

• count: Anzahl übereinstimmender Dokumente ermitteln, ohne sie zu übertragen

• get_document: Ein Dokument per ID abrufen

• bulk: Viele Dokumente gleichzeitig indizieren

Vorlagen (Templates)

• create_index_template: Eine zusammensetzbare Index-Vorlage erstellen oder aktualisieren

• get_index_template: Index-Vorlagen lesen

Aufgaben (Tasks)

• get_task: Fortschritt einer langlaufenden Aufgabe, wie sie zum Beispiel reindex zurückgibt

ES_ADMIN_TOOLS=true – Diagnose (nur lesend)

Diese Tools_können nur gelesen weden, ist in Prodktionen unbedenklich – genau das ist der Sinn dieser Group: Ein Agent kann so erklären, warum ein Index nicht gesund ist, ohne dass jemand sich am Cluster anmeldet.

• explain_allocation: Erklärt, warum ein Shard nicht zu ein Index gehört, mit the Entscheidung jedes Zuweisers

• list_shards: Status auf Shard-Ebene, zuerst der Kopien, die nicht STARTED sind

• get_nodes: Speicher, CPU, Last und Plattenauslastung pro Node

• get_index_stats: Zähler pro Index – Größe, Segmente, Indize, Suchen, Merges

• get_index_settings: Einstellungen eines Index (refresh_interval, Replicas, Schreibschutz-Blöcke)

• get_cluster_settings: Cluster-Einstellungen, die zur Laufzeit geändert wurden

• list_tasks: Was der Cluster gerade ausführt

ES_ALLOW_DESTRUCTIVE=true – nicht umkehrbar

Gedacht für eine Staging-Umgebung und standardmäßig deaktiviert, sodass Produktionssyststeme sie gar nicht erst erreichen können.

• delete_index: Löscht einen Index und dessen Daten

• delete_document: Löscht ein Dokument anhand der ID

• delete_by_query: Löscht alle Dokumente, die auf einen Query passen – asynchron, die einen Task-ID zurückbekommt und die Löschung im Hintergrund fortgesetzt wird

• delete_index_template: Löscht eine Index-Vorlage

Selbst ob die Flag aktiv ist, werden Wildcards, eine kommagetrennte Liste, * und _all abgelehnt: Sie wirken immer nur auf einen bestimmten Index. Ein Modell, das logs-* für einen einzelnen Index hält, bekommt eine Ablehnung statt eines geleerten Clusters.

So funktioniert's

1. Der MCP-Client analisiert die Anfrag und entscheidet, welche Elasticsearch-Operationen nötig sind.

2. Der MCP-Server führt diese Operationen aus (Indizes auflisten, Mappings abrufen, Suchen).

3. Der MCP-Client verarbeitet die Ergebnisse and präsentiert sie in ansprechender Form.

Related MCP server: Elasticsearch 7.x MCP Server

Erste Schritte

Voraussetzungen

• Eine Elasticsearch-7.x-Instanz (getestet gegen 7.8; der 7.17-Client unterstützt 6.8 bis 7.x)

• Elasticsearch-Zugangsdaten – ein API-Key oder ein Benutzername mit Passwort

• Ein MCP-Client: Claude Code, Claude Desktop, Codex, Cursor oder alles andere, das MCP über stdio spricht

Einmalige Anmeldung bei GitHub Packages

[!IMPORTANT] Dieses Paket wird in GitHub Packages veröffentlicht, nicht auf npmjs.com. GitHub Packages verlangt auch für öffentliche Pakete einen Token; bis du sie hinzufügst, schlägt jede Installation unten einem 401-Fehler. auf. Platz der Token in deiner benutzerbezogenen ~/.npmrc:

@agrica:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN ist ein Personaltokale mit dem Umfang read:packages.

Lass es and der eigenen ~/.npmrc, nicht in einer Projekt file liegen. Ein Token, der public Commit é una Kommittierung eines Repositoriums ist ein verlorener Tokenet, und einige Paketmanager weigern sich, ihn überhaupt darüber zu lesen.

Verbinde es mit deinem Client

Jedes Beispiel unten setzt ES_HOST und ES_API_KEY. Du kannst ES_USERNAME/ES_PASSWORD für Basic Auth verwenden, ES_ADMIN_TOOLS=true hinzufügen, um die Diagnose Tools zu erhalten, und ES_INSTANCE_LABEL setz, wenn mehr der eleme enter mehrere Instanzen definiert – siehe Configuration Options.

claude mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  --env ES_ADMIN_TOOLS=true \
  -- npx -y @agrica/elasticsearch7-mcp

Danach liste /mcp in der Sitzung den Server und die Tools.

Zwei Macken, die leicht falsch laufen können:

• Alles ein nach -- ist der Befehl, der den Server erstartet; ohne das würde Claude Code -y als ein eigenes Flagge probieren.

• Leg den Server Namen nicht direkt vor --env – die CLI list ihn auf als KEY=value-Paar und lehnt ihn ab. Oben steht der Name zum Zuerst, deshalb funktioniert es.

Der Serverwird im lokalen Scope hinzugefügt, also nur in diesem Projekt. Trage --scope user ein, um global verfügbar, oder --scope project um es in .mcp.json zu schreiben und mit Team zu teilen – beachte, dass ein eingechecktes .mcp.json deinen API-Key enthält, deshalb für Zugangsdaten lieber user scope.

Ändere claude_desktop_config.json – Settings > Developer > Edit Config öffnet sie, oder finde die Datei unter %APPDATA%\Claude\ auf Windows und unter ~/Library/Application Support/Claude/ auf macOS:

{
  "mcpServers": {
    "elasticsearch7": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://your-cluster:9200",
        "ES_API_KEY": "your-api-key",
        "ES_ADMIN_TOOLS": "true"
      }
    }
  }
}

Starte Claude Desktop dann neu; es liest diese Datei nur beim Start.

codex mcp add elasticsearch7 \
  --env ES_HOST=https://your-cluster:9200 \
  --env ES_API_KEY=your-api-key \
  -- npx -y @agrica/elasticsearch7-mcp

Oder schreibe es per Hand in ~/.codex/config.toml. Hinweis: Deser Codex schreibt den Abschnitt mcp_servers mit Unterstrich, und die Umgebungsvariablen stehen in einer eigenen Unterstruktur statt inline:

[mcp_servers.elasticsearch7]
command = "npx"
args = ["-y", "@agrica/elasticsearch7-mcp"]

[mcp_servers.elasticsearch7.env]
ES_HOST = "https://your-cluster:9200"
ES_API_KEY = "your-api-key"
ES_ADMIN_TOOLS = "true"

/mcp innerhalb von Codex bestätige, dass der Server geladen ist.

Der Server ist ein normaler stdio-MCP-Server, also funktioniert alles in der Rubrik Liste der MCP-Clients. Es sind drei Dinge nötig: Befehl npx, Argumente -y @agrica/elasticsearch7-mcp und die ES_*-Variablen in seiner Umgebung. Deser Server hört nie on einen Port und schreibt nichts außer dem MCP-Protokoll nach stdout – Diagnostik goes to stderr.

Konfiguration

Der Elasticsearch MCP Server unterstützt Einstellungen für die Verbindung zu Elasticsearch:

[!NOTE] Du musst n einen API-Schlüssel oder beides, Benutzername und Passwort für Auth angeben.

[!WARNING] ES_ADMIN_TOOLS and ES_ALLOW_DESTRUCTIVE haben keine Legacy-Alien ohne-Präfix, im Gegensatz zu den Verbindungsvariablen oben. Das ist Absicht: Wenn du eine variable ADMIN_TOOLS oder ALLOW_DESTRUCTIVE in der Umgebung hast, ist viel zu leicht unwillkürlich setzen, wenn du dabei löschbarsten.

Beide akzeptieren true oder 1; alles andere, einschließlich einer nicht gesetzten Variable, bedeutet aus.

Ergebnis-größe

Ein Tool-Ergebnis ist auf 32 KB (ES_MAX_RESULT_BYTES) begrenzt. Wichtig bei einem Logging-Cluster: Vonehoben per ein einzelnes list_shards über ein Jahr tagesindexe gab 385 KB – rund 96 000 Tokens – in einer einzigen Antwort, mehr als dies meisten Sitzungen halten können.

Wenn Ergebnis gekürzt wird, sagt es das, sagt wie viel es geht, und sagt, wie man die kleinere Frage stellen kann. Drei Tools richten ihre Antworten darauf aus:

• list_indicindizes und list_shards liefern eine einfach zu lesbare Antwort; die Zeilen als Text liegen in verbose.

• search begrenzt size auf 100 pro Aufruf und nennt die from-Seitenzahl.

• get_mappings brings zuerst die Felder, dann das rohe Mapping, so dass ein Index mit tausend Feldern noch die Antwort gibt.

Vier Tools – list_indices, list_shards, get_index_settings und get_mappings – liefern ihre Ausgabe auch als typisierte structurierte Ausgabe, so dass ein Client die Zeilen lesen statt den Text zu parsen. Diese Ausgabeseite wird aus dem Platz der lesbaren Antwort zusammengesetzt und meldet returned gegenüber total, damit eine Teil-Liste als Nummer sehenbar ist.

Run pnpm run measure führe gegen die build-Ausgabe aus, um aktuelle Werte für eigene Konfiguration zu sehen.

Mehrere Instanzen kennzeichnen

Zudem packaging

In den meisten Umgebungen ist Server er mehrere Instanzen. Der Eintrag pro Cluster ist sonst identisch, ein Client zeigt für zwei Server den gleichen. Namen an, und nichts unterscheidet. ES_INSTANCE_LABEL wird zum Titel des Servers; es ist die natürliche Stelle, um zu sagen, welche Umgebung ein Eintrag verbindet:

{
  "mcpServers": {
    "es7-prod": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-prod:9200",
        "ES_API_KEY": "prod-key",
        "ES_INSTANCE_LABEL": "production",
        "ES_ADMIN_TOOLS": "true"
      }
    },
    "es7-staging": {
      "command": "npx",
      "args": ["-y", "@agrica/elasticsearch7-mcp"],
      "env": {
        "ES_HOST": "https://es-staging:9200",
        "ES_API_KEY": "staging-key",
        "ES_INSTANCE_LABEL": "staging",
        "ES_ADMIN_TOOLS": "true",
        "ES_ALLOW_DESTRUCTIVE": "true"
      }
    }
  }
}

Das Paar ist die geplante Form: Diagnosewerkzeuge auf beiden Seiten, Löschfunktionen nur auf dem Staging-System. Die Produktion behält die Werkzeuge, die einen kranken Index erklären, und legt niemals ein Werkzeug frei, das Daten entfernen kann – das Modell kann das nicht aufrufen, was nie registriert wurde.

Das Label wird beim Start ebenfalls auf stderr ausgegeben. Dort sehen Sie nach, wenn ein Client eine Verbindung meldet, aber nicht zu erkennen ist, welcher Cluster geantwortet hat.

Konfiguration mehrerer URLs

Sie können mehrere Elasticsearch-Knoten für Hochverfügbarkeit und Lastverteilung konfigurieren:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agrica/elasticsearch7-mcp"
      ],
      "env": {
        "ES_HOST": "https://es-node1:9200,https://es-node2:9200,https://es-node3:9200",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

Der Client übernimmt automatisch Failover und Lastverteilung zwischen den konfigurierten Knoten.

Ausführen mit Docker

Jedes Release veröffentlicht ein Multi-Arch-Image (linux/amd64, linux/arm64) in die GitHub Container Registry:

docker pull ghcr.io/agrica/elasticsearch7-mcp:latest

Der Server kommuniziert über stdio, daher benötigt der Container ein interaktives stdin und keinen veröffentlichten Port. In einem MCP-Client:

{
  "mcpServers": {
    "elasticsearch7-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ES_HOST",
        "-e", "ES_API_KEY",
        "ghcr.io/agrica/elasticsearch7-mcp:latest"
      ],
      "env": {
        "ES_HOST": "your-elasticsearch-host",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

[!NOTE] Wie das npm-Paket befindet sich das Image in GitHub Packages: Das Abrufen erfordert ein Token mit dem Bereich read:packages, auch wenn das Repository öffentlich ist.

Das Image braucht keinen veröffentlichten Port und kein Volume: Es kommuniziert über stdio; der MCP-Client verwaltet dessen stdin und stdout.

Beispielabfragen

[!TIP] Hier sind einige natürlichsprachige Abfragen, die Sie mit Ihrem MCP-Client ausprobieren können.

Cluster-Verwaltung

• „Wie ist der Gesundheitsstatus meines Elasticsearch-Clusters?"

• „Wie viele aktive Knoten sind in meinem Cluster?"

Indexoperationen

• „Welche Indizes habe ich in meinem Elasticsearch-Cluster?"

• „Erstellen Sie einen neuen Index namens 'users' mit 3 Shards und 1 Replika."

• „Führen Sie einen Reindex von 'old_index' nach 'new_index' durch."

Mapping-Verwaltung

• „Zeigen Sie mir die Feldzuordnungen für den 'products' Indizes."

• „Fügen Sie dem Index 'products' ein Feld vom Typ 'keyword' mit dem Namen 'tags' hinzu."

Such- und Datenbetriebe

• „Finden Sie alle Bestellungen über 500 $ aus dem letzten Monat."

• „Welche Produkte haben die meisten 5-Sterne-Bewertungen erhalten?"

• „Importieren Sie diese Kundendatensätze per Bulk in den Index 'customers'."

Vorlagenverwaltung

• „Erstellen Sie eine Indizesvorlage für Logs mit dem Muster 'logs-*'."

• „Zeigen Sie mir alle meine Indexvorlagen."

Diagnosefunktionen (benötigt ES_ADMIN_TOOLS=true)

• „Der Index 'logs-2024' ist gelb – warum sind seine Shards nicht zugewiesen?"

• „Ist ein Knoten in der Nähe eines Disk-Watermarks?"

• „Welcher ist der größte Indizes, und wie viel davon sind gelöschte Dokumente?"

• „Hat jemand die Shard-Zuweisung in diesem Cluster deaktiviert?"

• „Läuft noch ein Reindex?"

Destruktive Operationen (benötigt ES_ALLOW_DESTRUCTIVE=true)

• „Löschen Sie diesen 'smoke-test-source'-Index."

• „Entfernen aus dem Index 'logs-archive' alle Dokumente, die älter als 2024 sind."

Problembehandlung

Einen Fehler gefunden oder fehlt Ihnen ein Werkzeug? Erstellen Sie ein Issue im GitHub-Repository. Wenn Sie am Code arbeiten möchten, beginnen Sie mit CONTRIBUTING.md.