Elasticsearch

by cr7258

100 544 downloads Not rated yet Apache-2.0
GitHub Website

About

Enables natural language interaction with Elasticsearch clusters for querying, indexing, and management operations via Docker-deployed infrastructure.

Details

Repository
cr7258/elasticsearch-mcp-server
License
Apache-2.0

Explore

- Tools for index, document, cluster, alias, and analyzer operations
- Multi‑cluster configuration with named clusters and a default target
- Authentication via username/password or API key (Elasticsearch)
- Option to disable high‑risk write operations
- Both stdio and SSE transport support
- Bearer token authentication for HTTP transports

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Elasticsearch
    Command (node, npx, python, etc.) uvx
    Arguments
    • Argument 1 elasticsearch-mcp-server
    Environment
    • DEFAULT_CLUSTER prod
    • 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>"}}

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

- ELASTICSEARCH_USERNAME: Username for basic authentication
- ELASTICSEARCH_PASSWORD: Password for basic authentication
- OPENSEARCH_USERNAME: Username for OpenSearch basic authentication
- OPENSEARCH_PASSWORD: Password for OpenSearch basic authentication

- ELASTICSEARCH_API_KEY: API key for](https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15)ElasticsearchorElastic CloudAuthentication.

- 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)

By default, the server uses a single Elasticsearch cluster fromELASTICSEARCH_HOSTS,ELASTICSEARCH_USERNAME,ELASTICSEARCH_PASSWORD, andELASTICSEARCH_API_KEY, or a single OpenSearch cluster fromOPENSEARCH_HOSTS,OPENSEARCH_USERNAME, andOPENSEARCH_PASSWORD. To configure multiple named clusters, setELASTICSEARCH_CLUSTERS(orOPENSEARCH_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:

{ "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" } } } }

For better readability, pointELASTICSEARCH_CLUSTERS_FILE(orOPENSEARCH_CLUSTERS_FILE) at a standalone JSON file instead. The value is just a path so it avoids the JSON-in-JSON escaping:

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

{ "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>" } }

Every tool accepts an optionalclusterparameter. If omitted, the server usesDEFAULT_CLUSTER. WhenDEFAULT_CLUSTERis not set, the first cluster in the JSON object is used as the default. A tool call targeting a specific cluster looks like:

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

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.

- Authentication isonly applicablefor HTTP transports (sse,streamable-http). Thestdiotransport uses local process communication and doesn't require authentication.
- IfMCP_API_KEYisnot set, the MCP server will be accessiblewithout authentication. This is a security risk when exposing the server over a network.
- For production deployments with HTTP transports,always setMCP_API_KEY.

# 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"

- 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)

WhenDISABLE_HIGH_RISK_OPERATIONSis 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_document
- delete_document
- delete_by_query

Optionally, you can specify a comma-separated list of operations to disable in theDISABLE_OPERATIONSenvironment variable.

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

Opt in to serialize tool-result payloads asGCF(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.

structuredContentis 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 canonicalint64numeric 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 whenRESPONSE_FORMATis unset.

Reproduce the token comparison:uv run --with tiktoken python benchmarks/gcf_benchmark.py.

Start the Elasticsearch/OpenSearch cluster using Docker Compose:

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

The default Elasticsearch username iselasticand password istest123. The default OpenSearch username isadminand password isadmin.

You can access Kibana/OpenSearch Dashboards fromhttp://localhost:5601.

Usinguvxwill automatically install the package from PyPI, no need to clone the repository locally. Add the following configuration to 's config fileclaude_desktop_config.json.

// 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" } } } }

general_api_request

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

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.

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.

get_cluster_health

Returns basic information about the health of the cluster.

get_cluster_stats

Returns high-level overview of cluster statistics.

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.

analyze_text

Analyze text using a specified analyzer or custom analysis chain. Useful for debugging search queries and understanding how text is tokenized.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "elasticsearch": {
            "env": {
                "DEFAULT_CLUSTER": "prod",
                "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>\"}}"
            },
            "args": [
                "elasticsearch-mcp-server"
            ],
            "command": "uvx"
        }
    }
}

Linux

{
    "env": {
        "DEFAULT_CLUSTER": "prod",
        "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>\"}}"
    },
    "args": [
        "elasticsearch-mcp-server"
    ],
    "command": "uvx"
}

Macos

{
    "env": {
        "DEFAULT_CLUSTER": "prod",
        "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>\"}}"
    },
    "args": [
        "elasticsearch-mcp-server"
    ],
    "command": "uvx"
}

Windows

{
    "env": {
        "DEFAULT_CLUSTER": "prod",
        "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>\"}}"
    },
    "args": [
        "/c",
        "uvx",
        "elasticsearch-mcp-server"
    ],
    "command": "cmd"
}

API Key Authentication (Elasticsearch only) - Recommended

- ELASTICSEARCH_API_KEY: API key for](https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15)ElasticsearchorElastic CloudAuthentication.

- 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)

By default, the server uses a single Elasticsearch cluster fromELASTICSEARCH_HOSTS,ELASTICSEARCH_USERNAME,ELASTICSEARCH_PASSWORD, andELASTICSEARCH_API_KEY, or a single OpenSearch cluster fromOPENSEARCH_HOSTS,OPENSEARCH_USERNAME, andOPENSEARCH_PASSWORD. To configure multiple named clusters, setELASTICSEARCH_CLUSTERS(orOPENSEARCH_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:

{ "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" } } } }

For better readability, pointELASTICSEARCH_CLUSTERS_FILE(orOPENSEARCH_CLUSTERS_FILE) at a standalone JSON file instead. The value is just a path so it avoids the JSON-in-JSON escaping:

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

{ "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>" } }

Every tool accepts an optionalclusterparameter. If omitted, the server usesDEFAULT_CLUSTER. WhenDEFAULT_CLUSTERis not set, the first cluster in the JSON object is used as the default. A tool call targeting a specific cluster looks like:

{ "cluster": "staging", "index": "logs-*", "body": { "query": { "match_all": {} } } }
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Videos about Elasticsearch

Relevant YouTube tutorials, setups, and demos

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

— 88.2k 508.3k dl
Other

Redis

Redis MCP Server connects compatible AI clients with Redis databases, allowing models and agents to inspect and interact with Redis-backed data through Model…

5.0 88.2k 6.6k dl
Database

Brave Search

Brave Search MCP Server connects compatible AI clients with the Brave Search API, allowing models and agents to run web searches through Model Context Protocol…

— 88.1k 5.9k dl
Search

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

— 88.1k 6.7k dl
Other