
Elasticsearch Mcp Server
io.github.cr7258Published by GitHub account cr7258v2.0.15Updated Nov 10, 2026
MCP server for interacting with Elasticsearch
Overview
A local MCP server that lets an assistant search, index and administer Elasticsearch or OpenSearch clusters through dedicated tools.
- What you can do
- Search, read, create, update and delete documents, including delete-by-query
- List, inspect, create and delete indices and data streams
- Manage aliases and analyze text with a chosen analyzer
- Check cluster health and statistics
- Send arbitrary API requests for anything without a dedicated tool
- Target one of several named clusters per call
- When to use it
- Useful when an assistant needs to explore or query an Elasticsearch or OpenSearch cluster, debug search queries and mappings, or perform routine index and document maintenance. Also fits setups with several named clusters (for example production and staging) that the assistant should address selectively.
- Requirements
- Runs locally as a Python package, typically launched with uvx or uv. Needs a reachable Elasticsearch or OpenSearch endpoint via ELASTICSEARCH_HOSTS (or OPENSEARCH_HOSTS) and credentials: ELASTICSEARCH_API_KEY, or ELASTICSEARCH_USERNAME with ELASTICSEARCH_PASSWORD. Optional settings cover multiple named clusters, a default cluster, certificate verification, request timeout and a proxy.
Installation
In SourceWeft
- Open Elasticsearch Mcp Server in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Elasticsearch/OpenSearch MCP Server
[MseeP.ai Security Assessment Badge]
Overview
A Model Context Protocol (MCP) server implementation that provides Elasticsearch and OpenSearch interaction. This server enables searching documents, analyzing indices, and managing cluster through a set of tools.
Demo
https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
Features
General Operations
general_api_request: Perform a general HTTP API request. Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
Index Operations
list_indices: List all indices.get_index: Returns information (mappings, settings, aliases) about one or more indices.create_index: Create a new index.delete_index: Delete an index.create_data_stream: Create a new data stream (requires matching index template).get_data_stream: Get information about one or more data streams.delete_data_stream: Delete one or more data streams and their backing indices.
Document Operations
search_documents: Search for documents.index_document: Creates or updates a document in the index.get_document: Get a document by ID.delete_document: Delete a document by ID.delete_by_query: Deletes documents matching the provided query.
Cluster Operations
get_cluster_health: Returns basic information about the health of the cluster.get_cluster_stats: Returns high-level overview of cluster statistics.
Alias Operations
list_aliases: List all aliases.get_alias: Get alias information for a specific index.put_alias: Create or update an alias for a specific index.delete_alias: Delete an alias for a specific index.
Analyzer Operations
analyze_text: Analyze text using a specified analyzer or custom analysis chain. Useful for debugging search queries and understanding how text is tokenized.
Configure Environment Variables
The MCP server supports the following environment variables:
Basic Authentication (Username/Password)
ELASTICSEARCH_USERNAME: Username for basic authenticationELASTICSEARCH_PASSWORD: Password for basic authenticationOPENSEARCH_USERNAME: Username for OpenSearch basic authenticationOPENSEARCH_PASSWORD: Password for OpenSearch basic authentication
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 for named cluster configurations. When set, tools can target a specific cluster with the optionalclusterparameter.ELASTICSEARCH_CLUSTERS_FILE/OPENSEARCH_CLUSTERS_FILE: Path to a JSON file with the clusters object. Recommended when the configuration is embedded inside another JSON file (e.g. the MCP client config) because it avoids JSON-in-JSON escaping. Takes precedence over the inline variable when both are set.DEFAULT_CLUSTER: Default cluster name to use when multi-cluster configuration is set and a tool call omitscluster(defaults to the first configured cluster).VERIFY_CERTS: Whether to verify SSL certificates (default:false)REQUEST_TIMEOUT: Request timeout in seconds (optional, uses client default if not set)ELASTICSEARCH_PROXY/OPENSEARCH_PROXY: Route all requests through a proxy (optional). Supported schemes arehttp://,https://,socks5://andsocks5h://, e.g.socks5h://127.0.0.1:1080for an SSH dynamic port forward (ssh -D 1080 bastion). Usesocks5hwhen the cluster host name only resolves on the proxy side. In a multi-cluster configuration, setproxyper cluster; it overrides the environment variable.
Multiple 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 inside the MCP server configuration. Because the value is a JSON string embedded in another JSON file, the inner quotes need to be escaped:
For better readability, point ELASTICSEARCH_CLUSTERS_FILE (or OPENSEARCH_CLUSTERS_FILE) at a standalone JSON file instead. The value is just a path so it avoids the JSON-in-JSON escaping:
/etc/mcp/es-clusters.json:
Here only staging is reached through a SOCKS proxy, prod connects directly.
Every tool accepts an optional cluster parameter. If omitted, the server uses DEFAULT_CLUSTER. When DEFAULT_CLUSTER is not set, the first cluster in the JSON object is used as the default. A tool call targeting a specific cluster looks like:
MCP Server Authentication (HTTP Transports Only)
When running the MCP server with HTTP-based transports (SSE or Streamable HTTP), you can enable Bearer token authentication to protect the server from unauthorized access.
MCP_API_KEY: API key for MCP server authentication. Clients must includeAuthorization: Bearer <MCP_API_KEY>header.
Important Security Notes:
- Authentication is only applicable for HTTP transports (
sse,streamable-http). Thestdiotransport uses local process communication and doesn't require authentication. - If
MCP_API_KEYis not set, the MCP server will be accessible without authentication. This is a security risk when exposing the server over a network. - For production deployments with HTTP transports, always set
MCP_API_KEY.
Disable High-Risk Operations
DISABLE_HIGH_RISK_OPERATIONS: Set totrueto disable all write operations (default:false)DISABLE_OPERATIONS: Comma-separated list of specific operations to disable (optional, uses default write operations list if not set)
When DISABLE_HIGH_RISK_OPERATIONS is set to true, all MCP tools that perform write operations are completely hidden from the MCP client. In this mode, the following MCP tools are disabled by default.
-
Index Operations:
create_indexdelete_index
-
Document Operations:
index_documentdelete_documentdelete_by_query
-
Data Stream Operations:
create_data_streamdelete_data_stream
-
Alias Operations:
put_aliasdelete_alias
-
General API Operations:
general_api_request
Optionally, you can specify a comma-separated list of operations to disable in the DISABLE_OPERATIONS environment variable.
GCF Response Encoding (optional)
Opt in to serialize tool-result payloads as GCF (Graph Compact Format), a token-optimized wire format, in the content block the model reads. Elasticsearch returns large, uniform record sets (search hits, aggregation buckets, mappings), the shape GCF compacts best: on representative responses it is ~39% fewer tokens than compact JSON (40% on search hits), losslessly.
structuredContent is preserved unchanged, so a tool's declared output schema still validates and any non-model client keeps receiving JSON; only the model-facing text block is re-encoded. Encoding is fail-safe: any error, including a value outside GCF's canonical int64 numeric domain (which GCF rejects rather than silently approximating), leaves the original JSON result untouched, so a tool call is never dropped over encoding. Default behavior is unchanged when RESPONSE_FORMAT is unset.
Reproduce the token comparison: uv run --with tiktoken python benchmarks/gcf_benchmark.py.
Start Elasticsearch/OpenSearch Cluster
Start the Elasticsearch/OpenSearch cluster using Docker Compose:
The default Elasticsearch username is elastic and password is test123. The default OpenSearch username is admin and password is admin.
You can access Kibana/OpenSearch Dashboards from http://localhost:5601.
Stdio
Option 1: Using uvx
Using uvx will automatically install the package from PyPI, no need to clone the repository locally. Add the following configuration to 's config file claude_desktop_config.json.
Option 2: Using uv with local development
Using uv requires cloning the repository locally and specifying the path to the source code. Add the following configuration to Claude Desktop's config file claude_desktop_config.json.
SSE
Option 1: Using uvx
Option 2: Using uv
Streamable HTTP
Option 1: Using uvx
Option 2: Using uv
Compatibility
The MCP server is compatible with Elasticsearch 7.x, 8.x, and 9.x. By default, it uses the Elasticsearch 8.x client (without a suffix).
To use the Elasticsearch 7.x client, run the elasticsearch-mcp-server-es7 variant. For Elasticsearch 9.x, use elasticsearch-mcp-server-es9. For example:
If you want to run different Elasticsearch variants (e.g., 7.x or 9.x) locally, simply update the elasticsearch dependency version in pyproject.toml, then start the server with:
Kubernetes Deployment
The Docker image is published to ghcr.io/cr7258/elasticsearch-mcp-server and the Helm chart is available as an OCI artifact at oci://ghcr.io/cr7258/charts/elasticsearch-mcp-server repository.
For full installation instructions, configuration reference, and usage examples see the Helm chart README.
License
This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.
Source: README.md at commit 90ae064
Tools
0Version history
1- v2.0.15LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts