MCP 服务器

elasticsearch-mcp

Enables AI assistants to search, analyze, and interact with Elasticsearch through natural language.

README

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

Guide	Description
Installation	Complete installation guide
Configuration	All configuration options
Tools Reference	Detailed tool documentation
Usage Examples	Common usage patterns
OAuth Setup	Claude.ai integration with SSO

Available Tools

Connection & Cluster

Tool	Description
`connect`	Connect to the cluster
`disconnect`	Close connections
`cluster_health`	Get cluster health status
`cluster_info`	Get cluster version and info

Index Operations

Tool	Description
`list_indices`	List all indices
`describe_index`	Get index mappings and settings
`get_index_stats`	Get index statistics

Search & Query

Tool	Description
`search`	Execute Query DSL search
`search_simple`	Simple query string search
`count`	Count matching documents
`get_document`	Get document by ID

Aggregations

Tool	Description
`aggregate`	Run aggregation queries
`terms_aggregation`	Quick terms aggregation
`date_histogram`	Time-based aggregations

Document Operations

Tool	Description
`index_document`	Create/update document
`update_document`	Partial document update
`delete_document`	Delete document

Export & Knowledge

Tool	Description
`export_to_json`	Export results to JSON
`export_to_csv`	Export results to CSV
`save_knowledge`	Save learned information
`get_all_knowledge`	Retrieve saved knowledge

Configuration

Required Variables

Variable	Description
`ES_HOST`	Elasticsearch host URL

Authentication (choose one)

Variable	Description
`ES_API_KEY`	API key authentication
`ES_USERNAME` + `ES_PASSWORD`	Basic authentication
`ES_CLOUD_ID`	Elastic Cloud ID

Safety Settings

Variable	Default	Description
`ES_READ_ONLY`	`false`	Block all write operations
`ES_MAX_RESULTS`	`1000`	Maximum results per query
`ES_BLOCKED_INDICES`	`.security*,...`	Indices to hide

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/