Elasticsearch

Elasticsearch MCP Server

Enhanced Elasticsearch MCP Server Solution - Security & Threat Analysis Focused

This is a professional security-focused solution maintained by TocharianOU. It enables comprehensive interaction with all Elasticsearch APIs, specifically optimized for security analysis, threat detection, and incident investigation. Features include advanced security monitoring, anomaly detection, threat hunting, root cause analysis, and comprehensive audit capabilities.

Key Security Features:

• Real-time threat detection and security monitoring
• Advanced machine learning for anomaly detection
• Root cause analysis and attack chain tracking
• Security incident investigation and forensics
• Compliance monitoring and audit reporting

---

Note: This solution is designed for security professionals, SOC teams, and threat analysts.

Connect to your Elasticsearch data directly from any MCP Client (such as Claude Desktop) using the Model Context Protocol (MCP). Interact with your Elasticsearch security data through natural language queries for advanced threat analysis and incident response.

Prerequisites

• An Elasticsearch instance
• Elasticsearch authentication credentials (API key or username/password)
• MCP Client (e.g. Claude Desktop) or HTTP client for remote access

Multi-Version Elasticsearch Support

Automatically supports Elasticsearch 5.x - 9.x with intelligent version detection:

Key Features:

• Automatic version detection - No manual configuration needed
• Smart client selection - Loads the right client for your ES version
• Adaptive features - Disables unsupported tools (e.g., Data Streams on ES < 7.9, ES|QL on ES < 8.11)
• Version-specific optimizations - Handles API differences transparently

What happens:

Connect → Detect ES version → Load matching client → Register compatible tools

The Query Harness (v0.9.0)

Since v0.9.0 the server ships a query harness: a deterministic layer between the AI model and your cluster. The design philosophy is simple:

The model steers; the harness knows.

Intent ("find failed logins by user") belongs to the model.

Correctness (real field names, aggregatability, version quirks) belongs to the harness.

What this means in practice — at the level of principles, not internals:

• Live truth beats bundled knowledge beats model memory. Every query is checked against the cluster's actual field capabilities before it runs. A bundled ECS (Elastic Common Schema) vocabulary provides *meaning*; the live cluster provides *existence*. The model's own recollection is never trusted.
• Unambiguous mistakes are fixed silently; ambiguous ones become guidance. The classic example: a spurious .keyword suffix on modern ECS mappings is auto-corrected (and the correction is reported); an unknown field blocks the doomed query and returns the nearest real fields instead of a provider error.
• Field knowledge stays out of the context window. The full ECS dictionary (thousands of fields) lives in process memory. The model retrieves only the handful it needs, on demand, via lookup_fields.
• Every failure must be actionable. Raw Elasticsearch errors are rewritten with live suggestions and index-naming advice (data stream vs. legacy Beats naming, internal indices that should be accessed via Kibana APIs, and so on).
• The model needs zero version knowledge. Naming eras, API differences and mapping-style differences (legacy text + .keyword subfield vs. modern bare keyword) are absorbed entirely by the harness. The same model behaves identically against ES 5.6 and ES 9.x — verified by a version test matrix covering nine watershed releases (5.6 → 9.0).
• An escape hatch always exists. Validation can be bypassed per call (skip_lint) when the model knows better — e.g. runtime fields defined outside the query. The harness assists; it never imprisons.

SSL/TLS Connection

To connect to Elasticsearch with a self-signed certificate or in a test environment, you can set the following environment variable:

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ This disables Node.js SSL certificate validation. Use only in development or testing environments. For production, always use a trusted CA certificate.

Installation & Setup

Install (or run) the server, point it at your cluster via environment variables, register it in your MCP client, then just start a conversation — the server connects and registers the tools your ES version supports.

Configuration Options

The Elasticsearch MCP Server supports the following configuration options:

Elasticsearch Configuration

Transport Mode Configuration (NEW in v0.3.0)

Transport Mode Details:

• Stdio mode (default): For Claude Desktop and local MCP clients
• HTTP Streamable mode: Runs as a standalone HTTP server for remote access, API integration, and web applications

Quick Start

Option 1: NPM Installation (Recommended)

1. Install globally via NPM

   npm install -g @tocharianou/elasticsearch-mcp

1. Run directly

   npx @tocharianou/elasticsearch-mcp

Option 2: GitHub Release (Standalone Package)

1. Download release package

• Go to GitHub Releases
• Download the latest .tar.gz file and its checksum files (.sha256 and .sha512)

1. Verify package integrity

   shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256

Should output: elasticsearch-mcp-v*.tar.gz: OK

1. Extract and use

   mkdir elasticsearch-mcp && cd elasticsearch-mcp

tar -xzf ../elasticsearch-mcp-v*.tar.gz

Run with your Elasticsearch credentials

ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js

Option 3: Source Installation

1. Clone the repository

   git clone https://github.com/TocharianOU/elasticsearch-mcp.git

cd elasticsearch-mcp

1. Install Dependencies

   npm install

1. Build the Project

   npm run build

1. Configure Claude Desktop App

• Open Claude Desktop App
• Go to Settings > Developer > MCP Servers
• Click Edit Config and add a new MCP Server with the following configuration:

For NPM Installation:

   {

"mcpServers": { "elasticsearch-mcp-server": { "command": "npx", "args": [ "@tocharianou/elasticsearch-mcp" ], "env": { "ES_URL": "your-elasticsearch-url", "ES_USERNAME": "elastic", "ES_PASSWORD": "your_pass", "NODE_TLS_REJECT_UNAUTHORIZED": "0" } } } }

For Source Installation:

   {

"mcpServers": { "elasticsearch-mcp-server-local": { "command": "node", "args": [ "/path/to/your/elasticsearch-mcp/dist/index.js" ], "env": { "ES_URL": "your-elasticsearch-url", "ES_USERNAME": "elastic", "ES_PASSWORD": "your_pass", "NODE_TLS_REJECT_UNAUTHORIZED": "0" } } } }

1. Debugging with MCP Inspector (optional)

   ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector

Installation & Integration Notes

If `npm install -g` misbehaves:

• *Permission errors (EACCES) on global install* — don't sudo. Either skip the global install entirely and let your MCP client run npx @tocharianou/elasticsearch-mcp (npx fetches on demand), or set a user-level prefix: npm config set prefix ~/.npm-global and add it to your PATH.
• *Slow or blocked registry* — use a mirror for the install only: npm install -g @tocharianou/elasticsearch-mcp --registry=https://registry.npmmirror.com.
• *Node version* — requires Node 18+ (node --version). Older Node fails at startup with ESM/fetch errors, not at install time.
• *npx cold start* — the first npx run downloads the package; if your MCP client times out on first connect, run npx @tocharianou/elasticsearch-mcp once in a terminal to warm the cache, then reconnect.
• *Fully offline hosts* — use the GitHub Release tarball (Option 2) and point your client at node /path/to/dist/index.js; nothing is fetched at runtime.

Claude Desktop — Settings → Developer → MCP Servers → Edit Config, then add the JSON block shown above. Restart the app after editing; the server appears in the tools list of a new conversation.

Claude Code (CLI) — register the server per-project or globally:

claude mcp add elasticsearch \

-e ES_URL=https://your-es:9200 -e ES_API_KEY=your-key \ -- npx @tocharianou/elasticsearch-mcp

Any other MCP client / platform integration — run in HTTP mode (MCP_TRANSPORT=http, see below) and point the client at http://host:port/mcp; this is the recommended shape for containerized platforms, one server instance per cluster connection.

Credentials hygiene — the env vars end up in your client's config file in plain text. Prefer a scoped, read-only API key (see *Elasticsearch Access Control* below) over superuser credentials.

Method 3: HTTP Streamable Mode (NEW in v0.3.0)

Run the server as a standalone HTTP service for remote access and API integration:

# Start HTTP server (default port 3000)

MCP_TRANSPORT=http \ ES_URL=your-elasticsearch-url \ ES_USERNAME=elastic \ ES_PASSWORD=your_pass \ npx @tocharianou/elasticsearch-mcp

Or with custom port and host

MCP_TRANSPORT=http \ MCP_HTTP_PORT=9000 \ MCP_HTTP_HOST=0.0.0.0 \ ES_URL=your-elasticsearch-url \ ES_USERNAME=elastic \ ES_PASSWORD=your_pass \ npx @tocharianou/elasticsearch-mcp

**HTTP Streamable