Happy slice of mcp pizzaMCP.pizza

elasticsearch-mcp-server

MCP.Pizza Chef: cr7258

Search systems like Elasticsearch and OpenSearch hold the logs and records many companies run on, and this lets an assistant question them for you: listing what is stored, finding matching documents, checking whether everything is healthy, and adding, updating or removing records on request. Several separate systems can be set up side by side and named, so you can ask about production or staging by name. You supply a login or access key for each one.

Data

Use This MCP server To

Search our logs for errors from the last hour Check whether the search system is healthy right now List what collections of records we actually have Pull up a single record by its identifier Clean out the test records I created yesterday Compare what production holds against staging

README

Elasticsearch/OpenSearch MCP Server

MseeP.ai Security Assessment Badge

Trust Score

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.

Elasticsearch MCP Server

Demo

elasticsearch-mcp-server-2.mp4

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 authentication
  • ELASTICSEARCH_PASSWORD: Password for basic authentication
  • OPENSEARCH_USERNAME: Username for OpenSearch basic authentication
  • OPENSEARCH_PASSWORD: Password for OpenSearch basic authentication

API Key Authentication (Elasticsearch only) - Recommended

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 optional cluster parameter.
  • 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 omits cluster (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)

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:

{
  "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, 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:

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

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:

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

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 include Authorization: Bearer <MCP_API_KEY> header.

Important Security Notes:

  • Authentication is only applicable for HTTP transports (sse, streamable-http). The stdio transport uses local process communication and doesn't require authentication.
  • If MCP_API_KEY is 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.
# 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

  • DISABLE_HIGH_RISK_OPERATIONS: Set to true to 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_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

Optionally, you can specify a comma-separated list of operations to disable in the DISABLE_OPERATIONS environment 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"

Start Elasticsearch/OpenSearch Cluster

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

// 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: 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.

// 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: Using 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: Using 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: Using 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: Using 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

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

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

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:

uvx elasticsearch-mcp-server-es7

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:

uv run src/server.py elasticsearch-mcp-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 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.

elasticsearch-mcp-server FAQ

Is this still maintained?
Yes. The project is actively worked on, with changes landing within the last week.
Which apps does it work in?
Claude Desktop is the documented setup, and any other app that speaks the same protocol can use it as well.
Do I need a key?
Yes. You provide either a username and password or an access key for your search system, saved in your app's settings.
Can I use this to search our logs in plain English?
Yes. You describe what you are looking for, and it runs the search and brings back the matching records.
Can it delete things?
Yes. It can create, change and delete both records and whole collections, so give it read-only credentials if that makes you nervous.
Does it work with OpenSearch too?
Yes. Both Elasticsearch and OpenSearch are supported, and you can register several systems and pick between them per question.
How hard is the setup?
You paste a short block into your app's settings with the address and login details, so no programming is required.