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

*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)

Security Tools (12 tools)

Index Tools (9 tools)

Cluster Tools (8 tools)

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