Elasticsearch OpenSearch MCP Server

What is Elasticsearch OpenSearch MCP Server about?

The server implements a set of tools that expose Elasticsearch and OpenSearch functionality through a standardized protocol, allowing clients to perform general API calls, manage indices, manipulate documents, monitor cluster health, and handle aliases.

How to use Elasticsearch OpenSearch MCP Server?

1. Configure environment variables – copy .env.example to .env and set host URLs, usernames, and passwords for Elasticsearch or OpenSearch.
2. Start a local cluster – use Docker Compose:

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

3. Run the MCP server – two common approaches:
   • uvx (no local checkout):

     uvx elasticsearch-mcp-server --transport streamable-http   # or --transport sse
     

   • uv with source (after cloning the repository):

     uv run src/server.py elasticsearch-mcp-server --transport streamable-http
     

4. Optionally specify host, port, and path using --host, --port, and --path flags.
5. Integrate with Claude Desktop or other MCP clients by adding the server definition to claude_desktop_config.json (see README for example JSON blocks).

Key features of Elasticsearch OpenSearch MCP Server

• General API request – any Elasticsearch/OpenSearch endpoint via general_api_request.
• Index operations: list, get, create, delete indices.
• Document operations: search, index (create/update), retrieve, delete, delete‑by‑query.
• Cluster operations: health status, statistics.
• Alias operations: list, get, create/update, delete aliases.
• Multiple transport modes: Server‑Sent Events (SSE) and Streamable HTTP.
• Compatibility: works with Elasticsearch 7.x, 8.x, 9.x and OpenSearch 1‑3.x (different binaries for each version).
• Docker‑based local cluster for quick testing.

Use cases of Elasticsearch OpenSearch MCP Server

• Search‑as‑a‑service for AI assistants that need to query document stores.
• Log and metrics aggregation where agents retrieve and filter logs from Elasticsearch clusters.
• Dynamic index management in CI/CD pipelines (create/delete indices on demand).
• Real‑time alerting by deleting documents matching certain criteria via delete_by_query.
• Multi‑cluster orchestration where a single MCP client controls both Elasticsearch and OpenSearch deployments.

FAQ from the Elasticsearch OpenSearch MCP Server

Q: Do I need to run the server locally? A: No. The server can be launched on any host reachable by your client. Only the Elasticsearch/OpenSearch endpoints must be reachable.

Q: Which transport should I choose? A: Use SSE for push‑style streaming of responses, or Streamable HTTP for conventional request/response semantics. Both are interchangeable from the client side.

Q: How do I work with Elasticsearch 7.x? A: Use the elasticsearch-mcp-server-es7 binary/command. It bundles the 7.x client library.

Q: Can I secure the MCP server? A: The server itself does not provide authentication; secure it behind a reverse proxy (e.g., Nginx) or run it in a trusted network. Authentication is handled by the underlying Elasticsearch/OpenSearch cluster.

Q: What Python version is required? A: The project follows the standard uv/uvx tooling, which supports Python 3.9+.

Elasticsearch/OpenSearch MCP Server

MCP Official Registry

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.

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

• 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_VERIFY_CERTS / OPENSEARCH_VERIFY_CERTS: Whether to verify SSL certificates (default: false)

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

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.