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

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.

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

Copy the .env.example file to .env and update the values accordingly.

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
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uvx",
      "args": [
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// 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
{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/src/elasticsearch_mcp_server",
        "run",
        "elasticsearch-mcp-server"
      ],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_USERNAME": "elastic",
        "ELASTICSEARCH_PASSWORD": "test123"
      }
    }
  }
}

// For OpenSearch
{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/src/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
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# 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
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

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

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

License

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