Elastic MCP Server

A comprehensive MCP (Model Context Protocol) server for Elasticsearch with InfoSec-focused tools for security management, search operations, index management, and cluster monitoring.

Features

• Security Management: Users, roles, API keys, privileges
• Search & Query: Full-text search, ES|QL, aggregations
• Index Operations: List, create, delete, mappings, settings
• Cluster Monitoring: Health, stats, nodes, shards
• Cross-Platform: Works on Windows, macOS, and Linux

Quick Start

1. Install Dependencies

npm install

2. Configure Environment

Copy .env.example to .env and configure your Elasticsearch connection:

# macOS/Linux
cp .env.example .env

# Windows (Command Prompt)
copy .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Edit .env with your credentials:

# Elasticsearch endpoint
ELASTIC_URL=https://your-deployment.es.region.azure.elastic-cloud.com

# API Key authentication (recommended)
ELASTIC_API_KEY_ENCODED=your-base64-encoded-api-key

3. Build

npm run build

4. Run

npm start

Configuration

Environment Variables

Variable	Required	Description
ELASTIC_URL	Yes	Elasticsearch cluster URL
ELASTIC_API_KEY_ENCODED	Yes*	Pre-encoded API key (base64)
ELASTIC_API_KEY_ID	Yes*	API key ID (alternative to encoded)
ELASTIC_API_KEY_SECRET	Yes*	API key secret (use with ID)
ELASTIC_USERNAME	Yes*	Basic auth username
ELASTIC_PASSWORD	Yes*	Basic auth password
ELASTIC_SKIP_SSL_VERIFY	No	Skip SSL verification (default: false)
ELASTIC_TIMEOUT	No	Request timeout in ms (default: 30000)
LOG_LEVEL	No	Logging level (default: info)

*One authentication method is required: encoded API key, ID+secret, or username+password.

Authentication Methods

API Key (Recommended)

Use the pre-encoded API key from the Elasticsearch API key creation response:

ELASTIC_API_KEY_ENCODED=YWNCT3hKc0JjVEtMYUN5ZWVNa046UGR4OUxwOFRtY2R5WElfTjBvMEhrQQ==

Separate ID and Secret

If you have the raw ID and secret:

ELASTIC_API_KEY_ID=acBOxJsBcTKLaCyeeMkN
ELASTIC_API_KEY_SECRET=Pdx9Lp8TmcdyXI_N0o0HkA

Basic Auth (Not Recommended)

ELASTIC_USERNAME=elastic
ELASTIC_PASSWORD=your-password

Available Tools

Search Tools (5 tools)

Tool	Description
search	Execute search queries using Elasticsearch Query DSL
esql_query	Execute ES|QL queries for data analysis
get_document	Retrieve a specific document by ID
count	Count documents matching a query
msearch	Execute multiple search queries in one request

Security Tools (12 tools)

Tool	Description
list_users	List all users in the security realm
get_user	Get detailed user information
create_user	Create a new user with roles
delete_user	Delete a user
set_user_enabled	Enable or disable a user
list_roles	List all defined roles
get_role	Get role details
create_role	Create or update a role
delete_role	Delete a role
list_api_keys	List API keys
create_api_key	Create a new API key
invalidate_api_key	Invalidate API keys
get_privileges	Get current user privileges
has_privileges	Check specific privileges
authenticate	Get current authenticated user info

Index Tools (9 tools)

Tool	Description
list_indices	List all indices with health and stats
get_index	Get index details
get_mappings	Get field mappings
get_settings	Get index settings
create_index	Create a new index
delete_index	Delete an index (requires confirmation)
refresh_index	Refresh an index
get_index_stats	Get index statistics
get_aliases	Get index aliases

Cluster Tools (8 tools)

Tool	Description
cluster_health	Get cluster health status
cluster_stats	Get comprehensive cluster statistics
cluster_info	Get basic cluster info and version
nodes_info	Get node information
nodes_stats	Get node statistics
pending_tasks	List pending cluster tasks
allocation_explain	Explain shard allocation
get_shards	Get shard allocation details

Usage Examples

Search for Security Events

{
  "tool": "search",
  "arguments": {
    "index": "logs-*",
    "query": {
      "bool": {
        "must": [
          { "match": { "event.category": "authentication" } },
          { "match": { "event.outcome": "failure" } }
        ]
      }
    },
    "size": 100,
    "sort": [{ "@timestamp": "desc" }]
  }
}

List All Users

{
  "tool": "list_users",
  "arguments": {}
}

Check Cluster Health

{
  "tool": "cluster_health",
  "arguments": {
    "level": "indices"
  }
}

Create an API Key

{
  "tool": "create_api_key",
  "arguments": {
    "name": "my-api-key",
    "expiration": "30d",
    "role_descriptors": {
      "read-only": {
        "cluster": ["monitor"],
        "indices": [{
          "names": ["logs-*"],
          "privileges": ["read"]
        }]
      }
    }
  }
}

Development

Run Tests

npm test

Run Tests with Coverage

npm run test:coverage

Lint

npm run lint

Watch Mode

npm run dev

Claude Desktop Integration

macOS / Linux

Config location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude/claude_desktop_config.json (Linux)

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["/path/to/elastic-mcp/dist/index.js"],
      "env": {
        "ELASTIC_URL": "https://your-deployment.es.region.azure.elastic-cloud.com",
        "ELASTIC_API_KEY_ENCODED": "your-encoded-api-key"
      }
    }
  }
}

Windows

Config location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\elastic-mcp\\dist\\index.js"],
      "env": {
        "ELASTIC_URL": "https://your-deployment.es.region.azure.elastic-cloud.com",
        "ELASTIC_API_KEY_ENCODED": "your-encoded-api-key"
      }
    }
  }
}

Windows Notes:

• Use double backslashes (\\) in JSON paths, or forward slashes (/) which also work
• Ensure Node.js is installed and available in your PATH
• Run npm install and npm run build before first use

Security Considerations

• API keys are never logged or exposed in responses
• All credentials must be provided via environment variables
• SSL certificate verification is enabled by default
• The delete_index tool requires explicit confirmation
• Created API keys return the encoded value but not the raw secret

License

MIT