Skip to main content
Glama
elasticsearch-mcp

elasticsearch-mcp

by bpamiri

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.

PyPI version Python 3.10+ License: Apache-2.0

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

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.

Available Tools

18 tools
aggregateB

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

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

    A3.7/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    18 tools is appropriate for an Elasticsearch MCP server, covering connection, cluster, indices, documents, search, and aggregations without being excessive or insufficient.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      14
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables querying Elasticsearch logs from AI assistants using natural language, with optional SSH tunnel support.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Elasticsearch clusters for health checks, index management, document CRUD operations, and search via natural language.
      10
      17 npm
      MIT