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