elasticsearch-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

elasticsearch-mcp is a Python MCP (Model Context Protocol) server that enables AI assistants to interact with Elasticsearch clusters. It uses the official elasticsearch Python client and provides tools for searching, aggregations, index management, and cluster operations.

Development Commands

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

pytest                                      # All tests
pytest tests/test_config.py                 # Single file
pytest --cov=elasticsearch_mcp --cov-report=html    # With coverage

ruff check .                                # Lint
ruff format .                               # Format
mypy src/                                   # Type check

Architecture

Transport Modes

The server (server.py:main) supports three transport modes via CLI args:

• stdio (default): elasticsearch-mcp — for Claude Desktop local connections
• SSE (legacy): elasticsearch-mcp --http — HTTP/SSE for centralized deployment
• Streamable HTTP: elasticsearch-mcp --streamable-http — for Claude.ai Integrations with OAuth

Tool Registration Pattern

Tools are registered via @mcp.tool() decorators on the module-level mcp FastMCP instance in server.py. Connection tools (connect, disconnect, cluster_health, etc.) are defined directly in server.py. Domain tools are implemented in tools/ modules and called from server.py tool wrappers.

Module Layout

src/elasticsearch_mcp/
├── server.py           # FastMCP instance, connection/cluster tools, CLI entry, transport modes
├── connection.py       # ConnectionManager: async connect/disconnect, health check
├── config.py           # Settings (pydantic-settings): all env vars including auth, watchdog, audit
├── auth/               # OAuth for Claude.ai Integrations (Streamable HTTP mode only)
│   ├── provider.py     # ESOAuthProvider: bridges Claude.ai DCR to external IdPs
│   ├── callback.py     # /oauth/callback route handler
│   ├── storage.py      # In-memory auth state (clients, codes, tokens, pending auths)
│   └── idp/            # Identity provider adapters
│       ├── base.py     # BaseIdPAdapter ABC (get_authorization_url, exchange_code, validate_token)
│       ├── duo.py      # Cisco Duo adapter
│       ├── auth0.py    # Auth0 adapter
│       └── oidc.py     # Generic OIDC adapter
├── tools/              # MCP tool implementations
│   ├── cluster.py      # cluster_health, cluster_info, list_nodes, cluster_stats
│   ├── indices.py      # list_indices, describe_index, get_index_stats, get_mappings, get_aliases
│   └── search.py       # search, search_simple, count, get_document, aggregate, terms_aggregation, date_histogram
├── resources/          # MCP resources (placeholder)
└── utils/              # Utility modules (placeholder)