Elasticsearch/OpenSearch MCP Server is a Model Context Protocol (MCP) server implementation that provides the ability to interact with Elasticsearch and OpenSearch. Through a set of tools, this server enables models to search documents, analyze indices, and manage clusters.
Main Capabilities
The project provides the following categories of tools:
General operations:
- general_api_request: Executes general HTTP API requests, suitable for Elasticsearch/OpenSearch APIs that do not have dedicated tools.
Index operations:
- list_indices: Lists all indices
- get_index: Returns information about one or more indices (mappings, settings, aliases)
- create_index: Creates a new index
- delete_index: Deletes an index
- create_data_stream: Creates a new data stream (requires a matching index template)
- get_data_stream: Gets information about one or more data streams
- delete_data_stream: Deletes one or more data streams and their backing indices
Document operations:
- search_documents: Searches documents
- index_document: Creates or updates a document in an index
- get_document: Gets a document by ID
- delete_document: Deletes a document by ID
- delete_by_query: Deletes documents matching a query
Cluster operations:
- get_cluster_health: Returns basic information about cluster health
- get_cluster_stats: Returns a high-level overview of cluster statistics
Alias operations:
- list_aliases: Lists all aliases
- get_alias: Gets alias information for a specific index
- put_alias: Creates or updates an alias for a specific index
- delete_alias: Deletes an alias for a specific index
Analyzer operations:
- analyze_text: Analyzes text using a specified analyzer or custom analysis chain, used for debugging search queries and understanding how text is tokenized.
Usage
Environment Variable Configuration
The server supports the following environment variables:
Basic authentication (username/password):
- ELASTICSEARCH_USERNAME: Elasticsearch basic authentication username
- ELASTICSEARCH_PASSWORD: Elasticsearch basic authentication password
- OPENSEARCH_USERNAME: OpenSearch basic authentication username
- OPENSEARCH_PASSWORD: OpenSearch basic authentication password
API key authentication (Elasticsearch only, recommended):
- ELASTICSEARCH_API_KEY: API key for Elasticsearch or Elastic Cloud authentication
Connection settings:
- ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: Comma-separated list of hosts (default:https://localhost:9200）
- ELASTICSEARCH_CLUSTERS / OPENSEARCH_CLUSTERS: Inline JSON object used to name cluster configurations. Once set, tools can target a specific cluster via the optional cluster parameter
- ELASTICSEARCH_CLUSTERS_FILE / OPENSEARCH_CLUSTERS_FILE: Path to a JSON file containing the clusters object. Recommended when the configuration is embedded in other JSON files (such as MCP client configuration), as it avoids JSON nesting escaping. When both are set, it takes precedence over the inline variable
- DEFAULT_CLUSTER: The default cluster name used when the cluster is omitted in tool calls under a multi-cluster configuration (defaults to the first configured cluster)
- VERIFY_CERTS: Whether to verify SSL certificates (default: false)
- REQUEST_TIMEOUT: Request timeout in seconds (optional)
Multi-Cluster Configuration
By default, the server uses a single Elasticsearch cluster from ELASTICSEARCH_HOSTS, ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD, and ELASTICSEARCH_API_KEY, or a single OpenSearch cluster from OPENSEARCH_HOSTS, OPENSEARCH_USERNAME, and OPENSEARCH_PASSWORD. To configure multiple named clusters, set ELASTICSEARCH_CLUSTERS (or OPENSEARCH_CLUSTERS) to a JSON object within the MCP server configuration.
For improved readability, you can point ELASTICSEARCH_CLUSTERS_FILE (or OPENSEARCH_CLUSTERS_FILE) to a standalone JSON file, whose value is only the path, avoiding JSON nesting escaping.
Each tool accepts an optional cluster parameter. When omitted, the server uses DEFAULT_CLUSTER. When DEFAULT_CLUSTER is not set, the first cluster in the JSON object is used as the default.
MCP Server Authentication (HTTP Transport Only)
When running the MCP server with an HTTP-based transport (SSE or Streamable HTTP), you can enable Bearer token authentication to prevent unauthorized access.
- MCP_API_KEY: API key for MCP server authentication. Clients must include the Authorization: Bearer <MCP_API_KEY> header.
Security considerations:
- Authentication applies only to HTTP transports (sse, streamable-http). The stdio transport uses local process communication and does not require authentication.
- If MCP_API_KEY is not set, the MCP server will be accessible without authentication. This poses a security risk when exposing the server over a network.
- For production deployments using HTTP transport, always set MCP_API_KEY.
Disabling High-Risk Operations
- DISABLE_HIGH_RISK_OPERATIONS: Set to true to disable all write operations (default: false)
- DISABLE_OPERATIONS: Comma-separated list of specific operations (optional; uses the default write operation list when not set)
When DISABLE_HIGH_RISK_OPERATIONS is set to true, all MCP tools that perform write operations will be completely hidden from MCP clients. The MCP tools disabled by default in this mode include:
- Index operations: create_index, delete_index
- Document operations: index_document, delete_document, delete_by_query
- Data stream operations: create_data_stream, delete_data_stream
- Alias operations: put_alias, delete_alias
- General API operations: general_api_request
You can alternatively specify a comma-separated list of operations to disable in the DISABLE_OPERATIONS environment variable.
GCF Response Encoding (Optional)
You can optionally serialize tool result payloads as GCF (Graph Compact Format), a token-optimized transport format used for content blocks read by the model. Elasticsearch returns large sets of uniform records (search hits, aggregation buckets, mappings), and GCFWhen running the MCP server with an HTTP-based transport (SSE or Streamable HTTP), you can enable Bearer token authentication to prevent unauthorized access.
- MCP_API_KEY: API key for MCP server authentication. Clients must include the Authorization: Bearer <MCP_API_KEY> header.
Security considerations:
- Authentication applies only to HTTP transports (sse, streamable-http). The stdio transport uses local process communication and does not require authentication.
- If MCP_API_KEY is not set, the MCP server will be accessible without authentication. This poses a security risk when exposing the server over a network.
- For production deployments using HTTP transport, always set MCP_API_KEY.
Disabling High-Risk Operations
- DISABLE_HIGH_RISK_OPERATIONS: Set to true to disable all write operations (default: false)
- DISABLE_OPERATIONS: Comma-separated list of specific operations (optional; uses the default write operation list when not set)
When DISABLE_HIGH_RISK_OPERATIONS is set to true, all MCP tools that perform write operations will be completely hidden from MCP clients. The MCP tools disabled by default in this mode include:
- Index operations: create_index, delete_index
- Document operations: index_document, delete_document, delete_by_query
- Data stream operations: create_data_stream, delete_data_stream
- Alias operations: put_alias, delete_alias
- General API operations: general_api_request
You can alternatively specify a comma-separated list of operations to disable in the DISABLE_OPERATIONS environment variable.
GCF Response Encoding (Optional)
You can optionally serialize tool result payloads as GCF (Graph Compact Format), a token-optimized transport format used for content blocks read by the model. Elasticsearch returns large sets of uniform records (search hits, aggregation buckets, mappings), and GCF This format compresses best: compared with compact JSON, it reduces tokens by about 39% on representative responses (about 40% on search hits), and it is lossless.
structuredContent remains unchanged, so the tool's declared output schema is still valid, and any non-model client still receives JSON; only the model-facing text block is re-encoded. The encoding is fail-safe: any error (including values outside the int64 numeric domain of the GCF specification, which GCF rejects rather than silently approximating) leaves the original JSON result unchanged, so tool calls are not dropped because of encoding. When RESPONSE_FORMAT is not set, the default behavior is unchanged.
Reproduce the token comparison: uv run --with tiktoken python benchmarks/gcf_benchmark.py
Start an Elasticsearch/OpenSearch cluster
Use Docker Compose to start an Elasticsearch/OpenSearch cluster. The default Elasticsearch username is elastic and the password is test123. The default OpenSearch username is admin and the password is admin. Available from http://localhost:5601 Access Kibana/OpenSearch Dashboards.
Installation options
Option 1: Use uvx Using uvx automatically installs the package from PyPI, with no need to clone the repository locally. Add the following configuration to Claude Desktop's configuration file claude_desktop_config.json.
Option 2: Use uv for local development Using uv requires cloning the repository locally and specifying the source code path. Add the following configuration to Claude Desktop's configuration file claude_desktop_config.json.
Streamable HTTP is also available.
Version compatibility
The MCP server is compatible with Elasticsearch 7.x, 8.x, and 9.x. By default it uses the Elasticsearch 8.x client (no suffix).
To use the Elasticsearch 7.x client, run the elasticsearch-mcp-server-es7 variant. For Elasticsearch 9.x, use elasticsearch-mcp-server-es9.
If you want to run a different Elasticsearch variant locally (such as 7.x or 9.x), simply update the elasticsearch dependency version in pyproject.toml, then start the server.
Kubernetes deployment
The Docker image is published to ghcr.io/cr7258/elasticsearch-mcp-server, and the Helm chart is available as an OCI artifact in the oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server repository. For complete installation instructions, configuration reference, and usage examples, see the Helm chart README.
License
This project is licensed under the Apache License Version 2.0.
