elasticsearch-mcp

An MCP (Model Context Protocol) server for Elasticsearch clusters. Enables AI assistants like Claude to search, analyze, and interact with Elasticsearch through natural language.

Features

• Natural Language Search: Ask Claude about your data in plain English

• Index Discovery: Explore indices, mappings, and field types

• Search & Aggregations: Full Query DSL and aggregation support

• Document Operations: Read, index, update, and delete documents

• Data Export: Export search results to JSON or CSV

• Knowledge Persistence: Claude remembers what it learns about your cluster

• Safety Controls: Read-only mode, index blocking, result limits

• Connection Watchdog: Automatic recovery from hung connections

• OAuth Integration: Deploy as a Claude.ai Custom Connector with SSO

Quick Start

1. Install

pip install elasticsearch-mcp

2. Configure Claude Desktop

Edit your Claude Desktop config file:

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

{
  "mcpServers": {
    "elasticsearch": {
      "command": "elasticsearch-mcp",
      "env": {
        "ES_HOST": "https://your-cluster.es.example.com:9200",
        "ES_API_KEY": "your-api-key",
        "ES_READ_ONLY": "true"
      }
    }
  }
}

3. Restart Claude Desktop

Quit and reopen Claude Desktop. You'll see a hammer icon indicating tools are available.

4. Start Chatting

Ask Claude about your Elasticsearch data:

"What indices are available?"

"Search for errors in the logs index from the last hour"

"Show me the top 10 users by request count"

"Describe the mappings for the customers index"

Documentation

Available Tools

Connection & Cluster

Index Operations

Search & Query

Aggregations

Document Operations

Export & Knowledge

Configuration

Required Variables

Authentication (choose one)

Safety Settings

Deployment Modes

Local (Default)

elasticsearch-mcp

HTTP/SSE Server

elasticsearch-mcp --http --host 0.0.0.0 --port 8080

Streamable HTTP (Claude.ai)

elasticsearch-mcp --streamable-http --host 0.0.0.0 --port 8080

Development

# Clone repository
git clone https://github.com/bpamiri/elasticsearch-mcp.git
cd elasticsearch-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

# Type check
mypy src/

Security

• API keys and passwords are never logged

• Configurable index blocklist

• Optional read-only mode

• Result size limits

• Query validation

License

Apache-2.0. See LICENSE for details.

Links

• PyPI Package

• GitHub Repository

• Issue Tracker

• MCP Documentation