Elasticsearch MCP Server
Elasticsearch/OpenSearch MCP Server
Ü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 BasisauthentifizierungELASTICSEARCH_PASSWORD: Passwort für die BasisauthentifizierungOPENSEARCH_USERNAME: Benutzername für die OpenSearch-BasisauthentifizierungOPENSEARCH_PASSWORD: Passwort für die OpenSearch-Basisauthentifizierung
API-Key-Authentifizierung (nur Elasticsearch) – Empfohlen
ELASTICSEARCH_API_KEY: API-Key für die Elasticsearch- oder Elastic Cloud-Authentifizierung.
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 Parameterclusterauf 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-Aufrufclusterweglä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 HeaderAuthorization: Bearer <MCP_API_KEY>einfügen.
Wichtige Sicherheitshinweise:
Die Authentifizierung ist nur für HTTP-Transports (
sse,streamable-http) anwendbar. Derstdio-Transport verwendet lokale Prozesskommunikation und erfordert keine Authentifizierung.Wenn
MCP_API_KEYnicht 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_KEYsetzen.
# 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 auftrue, 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_indexdelete_index
Dokument-Operationen:
index_documentdelete_documentdelete_by_query
Data-Stream-Operationen:
create_data_streamdelete_data_stream
Alias-Operationen:
put_aliasdelete_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=gcfstructuredContent 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 -dDer 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 /sseOption 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 /sseStreamable 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 /mcpOption 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 /mcpKompatibilitä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-es7Wenn 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-serverKubernetes-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 toolsanalyze_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
Scored across 20 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseBqualityDmaintenanceConnects to Elasticsearch databases using the Model Context Protocol, allowing users to query and interact with their Elasticsearch indices through natural language conversations.4Apache 2.0
- FlicenseBqualityDmaintenanceConnects 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-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT