elasticsearch-mcp
Supports authentication and connection to Elastic Cloud clusters using cloud ID.
Enables natural language search, analysis, and interaction with Elasticsearch clusters, including index exploration, document operations, and aggregations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@elasticsearch-mcp Search for errors in the logs index from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: otel-mcp-server
Quick Start
1. Install
pip install elasticsearch-mcp2. 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 |
Complete installation guide | |
All configuration options | |
Detailed tool documentation | |
Common usage patterns | |
Claude.ai integration with SSO |
Available Tools
Connection & Cluster
Tool | Description |
| Connect to the cluster |
| Close connections |
| Get cluster health status |
| Get cluster version and info |
Index Operations
Tool | Description |
| List all indices |
| Get index mappings and settings |
| Get index statistics |
Search & Query
Tool | Description |
| Execute Query DSL search |
| Simple query string search |
| Count matching documents |
| Get document by ID |
Aggregations
Tool | Description |
| Run aggregation queries |
| Quick terms aggregation |
| Time-based aggregations |
Document Operations
Tool | Description |
| Create/update document |
| Partial document update |
| Delete document |
Export & Knowledge
Tool | Description |
| Export results to JSON |
| Export results to CSV |
| Save learned information |
| Retrieve saved knowledge |
Configuration
Required Variables
Variable | Description |
| Elasticsearch host URL |
Authentication (choose one)
Variable | Description |
| API key authentication |
| Basic authentication |
| Elastic Cloud ID |
Safety Settings
Variable | Default | Description |
|
| Block all write operations |
|
| Maximum results per query |
|
| Indices to hide |
Deployment Modes
Local (Default)
elasticsearch-mcpHTTP/SSE Server
elasticsearch-mcp --http --host 0.0.0.0 --port 8080Streamable HTTP (Claude.ai)
elasticsearch-mcp --streamable-http --host 0.0.0.0 --port 8080Development
# 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
Available Tools
18 toolsaggregateB
Execute an aggregation query.
Args: index: Index to aggregate. aggs: Aggregation definition (e.g., {"status_count": {"terms": {"field": "status"}}}). query: Optional query to filter documents before aggregating.
Returns: Aggregation results with buckets and metrics.
Inputs: index (required), aggs (required), query. Returns: object
cluster_healthA
Get the health status of the Elasticsearch cluster.
Returns: Cluster health including status (green/yellow/red), nodes, and shards.
Inputs: no named parameters. Returns: object
cluster_infoA
Get cluster version and information.
Returns: Cluster name, version, build info, and compatibility versions.
Inputs: no named parameters. Returns: object
cluster_statsA
Get cluster-wide statistics.
Returns: Aggregated statistics for indices and nodes across the cluster.
Inputs: no named parameters. Returns: object
connectA
Connect to the Elasticsearch cluster.
Uses configuration from environment variables (ES_HOST, ES_API_KEY, etc.).
Returns: Connection status and cluster information.
Inputs: no named parameters. Returns: object
count_docsA
Count documents matching a query.
Args: index: Index to count. query: Optional query to filter documents.
Returns: Document count.
Inputs: index (required), query. Returns: object
date_histogramA
Get document counts over time (date histogram).
Args: index: Index to aggregate. field: Date field to aggregate on (e.g., "@timestamp"). interval: Time interval (minute, hour, day, week, month, year). query: Optional query to filter documents.
Returns: Time buckets with document counts.
Inputs: index (required), field (required), interval, query. Returns: object
describe_indexA
Get detailed information about an index.
Args: index: Name of the index to describe.
Returns: Index mappings (fields and types), settings, and statistics.
Inputs: index (required). Returns: object
disconnectA
Disconnect from the Elasticsearch cluster.
Returns: Disconnection status.
Inputs: no named parameters. Returns: object
es_searchA
Execute a search query using Elasticsearch Query DSL.
Args: index: Index to search (supports wildcards like "logs-*"). query: Elasticsearch query DSL (e.g., {"match": {"message": "error"}}). size: Maximum results to return (default: 10, max: from config). from_: Starting offset for pagination. sort: Sort specification (e.g., [{"@timestamp": "desc"}]).
Returns: Search hits with _id, _score, and _source fields.
Inputs: index (required), query, size, from_, +1 more. Returns: object
get_aliasesA
Get index aliases.
Args: index: Optional index name to filter aliases.
Returns: List of aliases with their target indices.
Inputs: index. Returns: object
get_documentB
Get a document by ID.
Args: index: Index containing the document. doc_id: Document ID.
Returns: Document source data or not found error.
Inputs: index (required), doc_id (required). Returns: object
get_index_statsB
Get statistics for an index.
Args: index: Name of the index.
Returns: Document counts, store size, indexing and search statistics.
Inputs: index (required). Returns: object
get_mappingsB
Get field mappings for an index.
Args: index: Name of the index.
Returns: Field definitions including types, analyzers, and options.
Inputs: index (required). Returns: object
list_indicesA
List all indices in the cluster.
Args: pattern: Index pattern to filter (supports wildcards like "logs-*"). include_hidden: Include hidden indices starting with "." (default: False).
Returns: List of indices with health, status, doc count, and size.
Inputs: pattern, include_hidden. Returns: object
list_nodesA
List all nodes in the cluster.
Returns: Node names, IPs, roles, and resource usage (CPU, memory, disk).
Inputs: no named parameters. Returns: object
search_simpleA
Execute a simple query string search.
Args: index: Index to search. q: Query string (supports Lucene syntax like "status:error AND level:critical"). size: Maximum results to return.
Returns: Search hits matching the query string.
Inputs: index (required), q (required), size. Returns: object
terms_aggregationB
Get top values for a field (terms aggregation).
Args: index: Index to aggregate. field: Field to get top values for (must be keyword or numeric). size: Number of top terms to return (default: 10). query: Optional query to filter documents.
Returns: Top field values with document counts.
Inputs: index (required), field (required), size, query. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool has a clearly distinct purpose. Aggregation tools are differentiated by type (general, date histogram, terms), search tools by query language, and cluster/index/document operations cover separate concerns without overlap.
All tool names follow a consistent snake_case convention with descriptive verb-noun patterns (e.g., list_indices, get_document, search_simple), making them predictable and easy to navigate.
18 tools is appropriate for an Elasticsearch MCP server, covering connection, cluster, indices, documents, search, and aggregations without being excessive or insufficient.
The tool set lacks fundamental CRUD operations for indices (create, delete, update) and documents (create, update, delete), leaving significant gaps for basic data management tasks.
Maintenance
Related MCP Connectors
Query, explore, and manage your databases through natural conversation.
Ask questions in plain language, get answers from your business database. No SQL required.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search your knowledge bases from any AI assistant using hybrid RAG.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables LLM-powered search with Elasticsearch, including query planning, expansion, and intelligent filtering for e-commerce.-
- AlicenseNot gradedqualityDmaintenanceEnables natural language querying and analysis of OpenTelemetry traces, metrics, and logs stored in Elasticsearch/OpenSearch, allowing AI assistants to investigate performance issues, find root causes, and explore system behavior.14MIT
- -licenseNot gradedqualityNot gradedmaintenanceEnables querying Elasticsearch logs from AI assistants using natural language, with optional SSH tunnel support.-
- AlicenseBqualityDmaintenanceEnables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.1017 npmMIT