Skip to main content
Glama
Elasticsearch MCP Server

Elasticsearch MCP Server

Elasticsearch/OpenSearch MCP Server

Trust Score

Überblick

Eine Implementierung eines Model Context Protocol (MCP)-Servers, der die Interaktion mit Elasticsearch und OpenSearch ermöglicht. Dieser Server ermöglicht das Durchsuchen von Dokumenten, das Analysieren von Indizes und die Verwaltung des Clusters über eine Reihe von Tools.

Related MCP server: Elasticsearch MCP Server

Demo

https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

Funktionen

Allgemeine Operationen

  • general_api_request: Führt eine allgemeine HTTP-API-Anfrage aus. Verwenden Sie dieses Tool für jede Elasticsearch/OpenSearch-API, für die kein dediziertes Tool vorhanden ist.

Index-Operationen

  • list_indices: Listet alle Indizes auf.

  • get_index: Gibt Informationen (Mappings, Einstellungen, Aliase) über einen oder mehrere Indizes zurück.

  • create_index: Erstellt einen neuen Index.

  • delete_index: Löscht einen Index.

  • create_data_stream: Erstellt einen neuen Data Stream (erfordert eine passende Index-Vorlage).

  • get_data_stream: Ruft Informationen über einen oder mehrere Data Streams ab.

  • delete_data_stream: Löscht einen oder mehrere Data Streams und ihre zugrunde liegenden Indizes.

Dokument-Operationen

  • search_documents: Durchsucht Dokumente.

  • index_document: Erstellt oder aktualisiert ein Dokument im Index.

  • get_document: Ruft ein Dokument anhand der ID ab.

  • delete_document: Löscht ein Dokument anhand der ID.

  • delete_by_query: Löscht Dokumente, die der angegebenen Abfrage entsprechen.

Cluster-Operationen

  • get_cluster_health: Gibt grundlegende Informationen über den Zustand des Clusters zurück.

  • get_cluster_stats: Gibt eine Übersicht über die Cluster-Statistiken zurück.

Alias-Operationen

  • list_aliases: Listet alle Aliase auf.

  • get_alias: Ruft Alias-Informationen für einen bestimmten Index ab.

  • put_alias: Erstellt oder aktualisiert einen Alias für einen bestimmten Index.

  • delete_alias: Löscht einen Alias für einen bestimmten Index.

Analyzer-Operationen

  • analyze_text: Analysiert Text mit einem angegebenen Analyzer oder einer benutzerdefinierten Analyse-Kette. Nützlich zum Debuggen von Suchabfragen und zum Verständnis, wie Text tokenisiert wird.

Umgebungsvariablen konfigurieren

Der MCP-Server unterstützt die folgenden Umgebungsvariablen:

Basisauthentifizierung (Benutzername/Passwort)

  • ELASTICSEARCH_USERNAME: Benutzername für die Basisauthentifizierung

  • ELASTICSEARCH_PASSWORD: Passwort für die Basisauthentifizierung

  • OPENSEARCH_USERNAME: Benutzername für die OpenSearch-Basisauthentifizierung

  • OPENSEARCH_PASSWORD: Passwort für die OpenSearch-Basisauthentifizierung

API-Key-Authentifizierung (nur Elasticsearch) – Empfohlen

Verbindungseinstellungen

  • ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Kommagetrennte Liste von Hosts (Standard: https://localhost:9200)

  • ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Inline-JSON-Objekt für benannte Cluster-Konfigurationen. Wenn gesetzt, können Tools mit dem optionalen Parameter cluster auf einen bestimmten Cluster abzielen.

  • ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: Pfad zu einer JSON-Datei mit dem Cluster-Objekt. Empfohlen, wenn die Konfiguration in eine andere JSON-Datei eingebettet ist (z. B. die MCP-Client-Konfiguration), da dies das Escaping von JSON-in-JSON vermeidet. Hat Vorrang vor der Inline-Variablen, wenn beide gesetzt sind.

  • DEFAULT_CLUSTER: Standard-Clustername, der verwendet wird, wenn eine Multi-Cluster-Konfiguration festgelegt ist und ein Tool-Aufruf cluster weglässt (standardmäßig der erste konfigurierte Cluster).

  • VERIFY_CERTS: Ob SSL-Zertifikate überprüft werden sollen (Standard: false)

  • REQUEST_TIMEOUT: Anfrage-Timeout in Sekunden (optional, verwendet den Client-Standard, wenn nicht gesetzt)

Multi-Cluster-Konfiguration

Standardmäßig verwendet der Server einen einzelnen Elasticsearch-Cluster aus ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD und ELASTICSEARCH_API_KEY oder einen einzelnen OpenSearch-Cluster aus OPENSEARCH_HOSTS, OPENSEARCH_USERNAME und OPENSEARCH_PASSWORD. Um mehrere benannte Cluster zu konfigurieren, setzen Sie ELASTICSEARCH_CLUSTERS (oder OPENSEARCH_CLUSTERS) auf ein JSON-Objekt innerhalb der MCP-Server-Konfiguration. Da der Wert ein JSON-String ist, der in eine andere JSON-Datei eingebettet ist, müssen die inneren Anführungszeichen escaped werden:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS": "{\"prod\": {\"hosts\": [\"https://prod-es:9200\"], \"api_key\": \"<PROD_API_KEY>\", \"verify_certs\": true}, \"staging\": {\"hosts\": [\"https://staging-es:9200\"], \"username\": \"elastic\", \"password\": \"<STAGING_PASSWORD>\"}}",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

Für bessere Lesbarkeit können Sie stattdessen ELASTICSEARCH_CLUSTERS_FILE (oder OPENSEARCH_CLUSTERS_FILE) auf eine eigenständige JSON-Datei verweisen lassen. Der Wert ist nur ein Pfad, sodass das Escaping von JSON-in-JSON vermieden wird:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_CLUSTERS_FILE": "/etc/mcp/es-clusters.json",
        "DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

/etc/mcp/es-clusters.json:

{
  "prod": {
    "hosts": ["https://prod-es:9200"],
    "api_key": "<PROD_API_KEY>",
    "verify_certs": true
  },
  "staging": {
    "hosts": ["https://staging-es:9200"],
    "username": "elastic",
    "password": "<STAGING_PASSWORD>"
  }
}

Jedes Tool akzeptiert einen optionalen Parameter cluster. Wenn dieser weggelassen wird, verwendet der Server DEFAULT_CLUSTER. Wenn DEFAULT_CLUSTER nicht gesetzt ist, wird der erste Cluster im JSON-Objekt als Standard verwendet. Ein Tool-Aufruf, der auf einen bestimmten Cluster abzielt, sieht wie folgt aus:

{
  "cluster": "staging",
  "index": "logs-*",
  "body": {
    "query": {
      "match_all": {}
    }
  }
}

MCP-Server-Authentifizierung (nur HTTP-Transports)

Wenn der MCP-Server mit HTTP-basierten Transports (SSE oder Streamable HTTP) ausgeführt wird, können Sie die Bearer-Token-Authentifizierung aktivieren, um den Server vor unbefugtem Zugriff zu schützen.

  • MCP_API_KEY: API-Key für die MCP-Server-Authentifizierung. Clients müssen den Header Authorization: Bearer <MCP_API_KEY> einfügen.

Wichtige Sicherheitshinweise:

  • Die Authentifizierung ist nur für HTTP-Transports (sse, streamable-http) anwendbar. Der stdio-Transport verwendet lokale Prozesskommunikation und erfordert keine Authentifizierung.

  • Wenn MCP_API_KEY nicht gesetzt ist, ist der MCP-Server ohne Authentifizierung zugänglich. Dies ist ein Sicherheitsrisiko, wenn der Server über ein Netzwerk bereitgestellt wird.

  • Für Produktionsbereitstellungen mit HTTP-Transports immer MCP_API_KEY setzen.

# Generate a secure API key (example using openssl)
export MCP_API_KEY=$(openssl rand -base64 32)

# Or set a custom API key
export MCP_API_KEY="your-secure-api-key-here"

Hochrisiko-Operationen deaktivieren

  • DISABLE_HIGH_RISK_OPERATIONS: Setzen Sie auf true, um alle Schreiboperationen zu deaktivieren (Standard: false)

  • DISABLE_OPERATIONS: Kommagetrennte Liste spezifischer Operationen, die deaktiviert werden sollen (optional, verwendet die Standard-Schreiboperationsliste, wenn nicht gesetzt)

Wenn DISABLE_HIGH_RISK_OPERATIONS auf true gesetzt ist, werden alle MCP-Tools, die Schreiboperationen ausführen, vollständig vor dem MCP-Client ausgeblendet. In diesem Modus sind die folgenden MCP-Tools standardmäßig deaktiviert.

  • Index-Operationen:

    • create_index

    • delete_index

  • Dokument-Operationen:

    • index_document

    • delete_document

    • delete_by_query

  • Data-Stream-Operationen:

    • create_data_stream

    • delete_data_stream

  • Alias-Operationen:

    • put_alias

    • delete_alias

  • Allgemeine API-Operationen:

    • general_api_request

Optional können Sie eine kommagetrennte Liste von Operationen angeben, die in der Umgebungsvariable DISABLE_OPERATIONS deaktiviert werden sollen.

# Disable High-Risk Operations
export DISABLE_HIGH_RISK_OPERATIONS=true
# Disable specific operations only
export DISABLE_OPERATIONS="delete_index,delete_document,delete_by_query"

GCF-Antwortkodierung (optional)

Sie können sich dafür entscheiden, die Tool-Ergebnis-Payloads als GCF (Graph Compact Format) zu serialisieren, ein tokenoptimiertes Drahtformat, im Inhaltsblock, den das Modell liest. Elasticsearch gibt große, gleichförmige Datensätze zurück (Suchtreffer, Aggregations-Buckets, Mappings), die Form, die GCF am besten komprimiert: Bei repräsentativen Antworten sind das ~39 % weniger Tokens als kompaktes JSON (40 % bei Suchtreffern), verlustfrei.

export RESPONSE_FORMAT=gcf

structuredContent bleibt unverändert erhalten, sodass das deklarierte Ausgabeschema eines Tools weiterhin validiert wird und jeder Nicht-Modell-Client weiterhin JSON erhält; nur der modellbezogene Textblock wird neu kodiert. Die Kodierung ist ausfallsicher: Jeder Fehler, einschließlich eines Werts außerhalb des kanonischen int64-Zahlenbereichs von GCF (den GCF ablehnt, anstatt ihn stillschweigend zu approximieren), lässt das ursprüngliche JSON-Ergebnis unverändert, sodass ein Tool-Aufruf niemals aufgrund der Kodierung verworfen wird. Das Standardverhalten bleibt unverändert, wenn RESPONSE_FORMAT nicht gesetzt ist.

Reproduzieren Sie den Token-Vergleich: uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Elasticsearch/OpenSearch-Cluster starten

Starten Sie den Elasticsearch/OpenSearch-Cluster mit Docker Compose:

# For Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d

# For OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d

Der Standard-Benutzername für Elasticsearch ist elastic und das Passwort ist test123. Der Standard-Benutzername für OpenSearch ist admin und das Passwort ist admin.

Sie können auf Kibana/OpenSearch Dashboards über http://localhost:5601 zugreifen.

Stdio

Option 1: Mit uvx

Die Verwendung von uvx installiert das Paket automatisch von PyPI, ohne dass das Repository lokal geklont werden muss. Fügen Sie die folgende Konfiguration zur Konfigurationsdatei claude_desktop_config.json hinzu.

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": [
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

Option 2: Mit uv und lokaler Entwicklung

Die Verwendung von uv erfordert das lokale Klonen des Repositorys und die Angabe des Pfads zum Quellcode. Fügen Sie die folgende Konfiguration zur Konfigurationsdatei claude_desktop_config.json von Claude Desktop hinzu.

// For Elasticsearch with username/password
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For Elasticsearch with API key
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<YOUR_ELASTICSEARCH_API_KEY>"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/elasticsearch-mcp-server",
        "run",
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

SSE

Option 1: Mit uvx

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uvx elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Option 2: Mit uv

# By default, the SSE MCP server will serve on http://127.0.0.1:8000/sse
uv run src/server.py elasticsearch-mcp-server --transport sse

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP

Option 1: Mit uvx

# export environment variables (with username/password)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# OR export environment variables (with API key)
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="<YOUR_ELASTICSEARCH_API_KEY>"

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uvx elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Option 2: Mit uv

# By default, the Streamable HTTP MCP server will serve on http://127.0.0.1:8000/mcp
uv run src/server.py elasticsearch-mcp-server --transport streamable-http

# The host, port, and path can be specified using the --host, --port, and --path options
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Kompatibilität

Der MCP-Server ist mit Elasticsearch 7.x, 8.x und 9.x kompatibel. Standardmäßig verwendet er den Elasticsearch-8.x-Client (ohne Suffix).

MCP-Server

Elasticsearch

elasticsearch-mcp-server-es7

Elasticsearch 7.x

elasticsearch-mcp-server

Elasticsearch 8.x

elasticsearch-mcp-server-es9

Elasticsearch 9.x

opensearch-mcp-server

OpenSearch 1.x, 2.x, 3.x

Um den Elasticsearch-7.x-Client zu verwenden, führen Sie die Variante elasticsearch-mcp-server-es7 aus. Für Elasticsearch 9.x verwenden Sie elasticsearch-mcp-server-es9. Zum Beispiel:

uvx elasticsearch-mcp-server-es7

Wenn Sie verschiedene Elasticsearch-Varianten (z. B. 7.x oder 9.x) lokal ausführen möchten, aktualisieren Sie einfach die Abhängigkeit elasticsearch in pyproject.toml und starten Sie den Server mit:

uv run src/server.py elasticsearch-mcp-server

Kubernetes-Bereitstellung

Das Docker-Image wird unter ghcr.io/cr7258/elasticsearch-mcp-server veröffentlicht und das Helm-Chart ist als OCI-Artefakt im Repository oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server verfügbar.

Vollständige Installationsanweisungen, Konfigurationsreferenz und Verwendungsbeispiele finden Sie in der Helm-Chart-README.

Lizenz

Dieses Projekt ist unter der Apache License Version 2.0 lizenziert – siehe die Datei LICENSE für Details.

Available Tools

20 tools
analyze_textB

Analyze text to see how it would be tokenized.

Use this tool to understand how Elasticsearch/OpenSearch tokenizes and transforms text using analyzers. This is essential for debugging search queries and understanding why certain documents match or don't match.

Inputs: text (required), index, filter, cluster, +5 more. Returns: object

create_data_streamB

Create a new data stream.

This creates a new data stream with the specified name. The data stream must have a matching index template before creation.

Inputs: name (required), cluster. Returns: object

create_indexC

Create a new index.

Inputs: index (required), body, cluster. Returns: object

delete_aliasC

Delete an alias for a specific index.

Inputs: name (required), index (required), cluster. Returns: object

delete_by_queryC

Deletes documents matching the provided query.

Inputs: body (required), index (required), cluster. Returns: object

delete_data_streamA

Delete one or more data streams.

Permanently deletes the specified data streams and all their backing indices.

Inputs: name (required), cluster. Returns: object

delete_documentC

Delete a document by ID.

Inputs: id (required), index (required), cluster. Returns: object

delete_indexC

Delete an index.

Inputs: index (required), cluster. Returns: object

general_api_requestA

Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.

Inputs: path (required), method (required), body, params, +1 more.

get_aliasC

Get alias information for a specific index.

Inputs: index (required), cluster. Returns: object

get_cluster_healthC

Returns basic information about the health of the cluster.

Inputs: cluster. Returns: object

get_cluster_statsB

Returns high-level overview of cluster statistics.

Inputs: cluster. Returns: object

get_data_streamC

Get information about one or more data streams.

Retrieves configuration, mappings, settings, and other information about the specified data streams.

Inputs: name, cluster. Returns: object

get_documentC

Get a document by ID.

Inputs: id (required), index (required), cluster. Returns: object

get_indexB

Returns information (mappings, settings, aliases) about one or more indices.

Inputs: index (required), cluster. Returns: object

index_documentC

Creates or updates a document in the index.

Inputs: index (required), document (required), id, cluster. Returns: object

list_aliasesB

List all aliases.

Inputs: cluster. Returns: result

list_indicesC

List all indices.

Inputs: cluster. Returns: result

put_aliasC

Create or update an alias for a specific index.

Inputs: body (required), name (required), index (required), cluster. Returns: object

search_documentsC

Search for documents.

Inputs: body (required), index (required), cluster. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action (index, document, alias, data stream, cluster, analysis, or generic API). Overlaps like get_index vs list_indices and get_alias vs list_aliases are cleanly separated by specificity. The general_api_request fallback is explicitly scoped to APIs without dedicated tools, so it does not create real misselection risk.

    Naming Consistency5/5

    Tools follow a consistent snake_case verb_noun convention (create_index, delete_document, get_cluster_health, put_alias, etc.). The only minor exception is general_api_request, but it still fits the overall readable naming style. There is no mixing of camelCase or conflicting verb patterns.

    Tool Count4/5

    At 20 tools, the surface is slightly heavy by the usual 3–15 guideline, but Elasticsearch is a broad domain and each tool covers a meaningful resource area. The set avoids extreme bloat and does not include redundant operations.

    Completeness4/5

    Core CRUD and lifecycle coverage exists for indices, documents, aliases, data streams, and cluster inspection, with search and text analysis included. Notable gaps remain—such as dedicated index template management (required for data streams), bulk operations, and update-by-query—but the general_api_request tool provides a workaround for any missing API.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with Elasticsearch clusters, allowing them to manage indices and execute search queries using natural language.
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      Connects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.
      4
      Apache 2.0
    • F
      license
      B
      quality
      D
      maintenance
      Connects to Elasticsearch clusters through the Model Context Protocol, enabling natural language querying and management of Elasticsearch data. Provides tools to search indices, list available indices, and retrieve index mappings.
      3
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.
      10
      17 npm
      MIT