Elasticsearch MCP Server: Complete Cluster Management Through Natural Language
Background
Elasticsearch 9.2 introduced native MCP (Model Context Protocol) support, enabling direct integration with AI assistants like Claude. However, the vast majority of production deployments still run on earlier versions (ES 5.x through 8.x) which lack this capability.
This project fills that gap by providing a standalone MCP server implementation built upon Elastic's official JavaScript client libraries, extending and maintaining the original codebase with full MCP protocol support.
Repository: GitHub - TocharianOU/elasticsearch-mcp: Elasticsearch MCP Server Solution Fork by TocharianOU
Package: @tocharianou/elasticsearch-mcp
License: Apache-2.0
Core Capabilities
This server exposes the complete Elasticsearch API through natural language interface. Every operation available through direct REST API calls becomes accessible conversationally:
Cluster & Shard Management:
-
Shard allocation control and rebalancing across nodes
-
Unassigned shard diagnosis and recovery
-
Cluster settings configuration
-
Node exclusion and decommissioning
-
Split, shrink, and clone operations
Index Lifecycle Management:
-
ILM policy creation with hot/warm/cold/frozen tiers
-
Policy assignment to index templates
-
Rollover configuration and monitoring
-
Snapshot lifecycle management
-
Data retention automation
Mapping & Analysis:
-
Dynamic mapping inspection and optimization
-
Field type analysis and memory profiling
-
Analyzer configuration and testing
-
Mapping updates and reindexing strategies
-
Field explosion detection
Search & Query:
-
Full-text search with arbitrary Query DSL
-
Complex aggregations (nested, pipeline, matrix)
-
Scroll and search_after for large result sets
-
Multi-search and count operations
-
Query profiling and performance analysis
Document Operations:
-
Single and bulk document indexing
-
Update by query with script transformations
-
Delete by query with conflict handling
-
Reindex within cluster or cross-cluster
-
Document routing and version control
Performance Optimization:
-
Segment analysis and force merge operations
-
Cache management (fielddata, query, request)
-
Refresh interval tuning
-
Merge policy configuration
-
Translog and flush settings
Template & Settings:
-
Index template creation and management
-
Component template composition
-
Dynamic index settings updates
-
Alias management and atomic swaps
-
Index codec and compression configuration
There are no artificial limitations. If your cluster supports an operation through its REST API, this MCP server can execute it through natural language commands.
Version Support
Elasticsearch 5.x - 9.x with automatic version detection and adaptive client library loading.
Technical Foundation
Built on Elastic's official @elastic/elasticsearch client libraries with full authentication support (API keys, basic auth, certificates). Operates in two transport modes:
-
stdio - for local MCP clients like Claude Desktop
-
HTTP - for remote access and API integration
Installation and Usage
npm install -g @tocharianou/elasticsearch-mcp
Configuration through environment variables:
export ES_URL="https://your-cluster:9200"
export ES_API_KEY="your-api-key"
# or use ES_USERNAME and ES_PASSWORD for basic auth
elasticsearch-mcp
Once running, the server accepts natural language commands through any MCP-compatible client. Describe what you need, and the server translates to appropriate Elasticsearch operations.
Example Interactions
Some typical usage patterns:
Performance diagnostics:
Show shard distribution across nodes with size and document counts
Get segment statistics for indices matching logs-2024*
Explain why shards are unassigned in the metrics-production index
Mapping analysis:
Pull complete mapping for security-events-2024.01 showing all field types
List all indices using dynamic field mapping
Find keyword fields that could be optimized to lower memory usage
Index lifecycle management:
Create ILM policy transitioning from hot to warm to cold storage with specific retention
Apply lifecycle policy to all indices matching application-logs-*
Show which indices are in warm phase and ready for force merge
Cluster optimization:
Identify over-sharded indices where shard count exceeds recommended ratios
Shrink index application-data-2023.12 from 5 shards to 2 shards
Force merge read-only indices older than 90 days to 1 segment per shard
Cross-cluster operations:
Reindex from source-cluster/logs-* to target-cluster/archive-logs-*
Compare shard allocation between production and disaster recovery clusters
Validate mapping compatibility before migration
The server interprets these requests, executes appropriate Elasticsearch API calls, and returns structured results. For complex operations spanning multiple API endpoints, it handles sequencing and error recovery automatically.
Use Cases
Operations & SRE: Rapid incident response and performance troubleshooting without API syntax overhead.
Security Operations: SIEM data investigation and threat hunting through conversational queries.
Data Platform Engineering: Cluster management across multiple Elasticsearch deployments from a unified interface.
Automation Development: Natural language operational runbooks that translate to validated Elasticsearch operations.
Project Status
Actively maintained with continuous testing against Elasticsearch 5.x through 9.x. Apache 2.0 licensed.
Contributions and issue reports welcome at GitHub - TocharianOU/elasticsearch-mcp: Elasticsearch MCP Server Solution Fork by TocharianOU.