playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Elasticsearch MCP server

Enables natural language interaction with Elasticsearch clusters for querying, indexing, and management operations via Docker-deployed infrastructure.
Back to servers
Setup instructions
Provider
cr7258
Release date
Jan 09, 2025
Language
Python
Stats
169 stars
View on GitHub

This MCP server implementation provides a bridge to Elasticsearch and OpenSearch, allowing you to search documents, analyze indices, and manage clusters through a standardized interface. It supports multiple transport types and offers a comprehensive set of tools for interacting with your search engine.

Installation and Setup

Prerequisites

  • Docker and Docker Compose (for running Elasticsearch/OpenSearch)
  • Python with uv or uvx package manager

Setting Up Elasticsearch or OpenSearch

  1. Start your preferred search engine 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

Default credentials:

  • Elasticsearch: username elastic, password test123
  • OpenSearch: username admin, password admin

Access the dashboard at http://localhost:5601

Environment Configuration

Copy the .env.example file to .env and update the values for your environment.

Running the MCP Server

Option 1: Using Stdio Transport (for Claude Desktop)

With uvx (recommended)

Add the following to your 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, replace with:

{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": [
        "opensearch-mcp-server"
      ],
      "env": {
        "OPENSEARCH_HOSTS": "https://localhost:9200",
        "OPENSEARCH_USERNAME": "admin",
        "OPENSEARCH_PASSWORD": "admin"
      }
    }
  }
}

With uv (local development)

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

Option 2: Using Server-Sent Events (SSE)

With uvx

# Set environment variables
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# Run with default settings (http://127.0.0.1:8000/sse)
uvx elasticsearch-mcp-server --transport sse

# Or customize host, port, and path
uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

With uv

# Run with default settings
uv run src/server.py elasticsearch-mcp-server --transport sse

# Or customize host, port, and path
uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Option 3: Using Streamable HTTP

With uvx

# Set environment variables
export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="test123"

# Run with default settings (http://127.0.0.1:8000/mcp)
uvx elasticsearch-mcp-server --transport streamable-http

# Or customize host, port, and path
uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

With uv

# Run with default settings
uv run src/server.py elasticsearch-mcp-server --transport streamable-http

# Or customize host, port, and path
uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Available Tools

General Operations

  • general_api_request: Perform a generic HTTP API request for any Elasticsearch/OpenSearch API

Index Operations

  • list_indices: View all indices
  • get_index: Get information about specific indices
  • create_index: Create a new index
  • delete_index: Remove an index

Document Operations

  • search_documents: Search for documents
  • index_document: Create or update a document
  • get_document: Retrieve a document by ID
  • delete_document: Remove a document by ID
  • delete_by_query: Delete documents matching a query

Cluster Operations

  • get_cluster_health: Check basic cluster health
  • get_cluster_stats: View high-level cluster statistics

Alias Operations

  • list_aliases: View all aliases
  • get_alias: Get alias information for a specific index
  • put_alias: Create or update an alias
  • delete_alias: Remove an alias

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "elasticsearch-mcp-server" '{"command":"uvx","args":["elasticsearch-mcp-server"],"env":{"ELASTICSEARCH_HOSTS":"https://localhost:9200","ELASTICSEARCH_USERNAME":"elastic","ELASTICSEARCH_PASSWORD":"test123"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "elasticsearch-mcp-server": {
            "command": "uvx",
            "args": [
                "elasticsearch-mcp-server"
            ],
            "env": {
                "ELASTICSEARCH_HOSTS": "https://localhost:9200",
                "ELASTICSEARCH_USERNAME": "elastic",
                "ELASTICSEARCH_PASSWORD": "test123"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "elasticsearch-mcp-server": {
            "command": "uvx",
            "args": [
                "elasticsearch-mcp-server"
            ],
            "env": {
                "ELASTICSEARCH_HOSTS": "https://localhost:9200",
                "ELASTICSEARCH_USERNAME": "elastic",
                "ELASTICSEARCH_PASSWORD": "test123"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later