Skip to main content
Glama
Elastic MCP Server

Elastic MCP Server

by schwarztim

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

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

Available Tools

37 tools
allocation_explainA

Explain why a shard is unassigned or why it remains on its current node.

Inputs: index, shard, primary.

authenticateB

Get information about the currently authenticated user.

Inputs: no named parameters.

cluster_healthB

Get the health status of the Elasticsearch cluster including node counts, shard status, and overall health.

Inputs: level, wait_for_status, timeout.

cluster_infoB

Get basic cluster information including version and build details.

Inputs: no named parameters.

cluster_statsB

Get comprehensive cluster statistics including indices, nodes, and resource usage.

Inputs: no named parameters.

countC

Count documents in an index that match a query.

Inputs: index (required), query.

create_api_keyC

Create a new API key for authentication.

Inputs: name (required), expiration, role_descriptors, metadata.

create_indexC

Create a new index with optional settings, mappings, and aliases.

Inputs: index (required), settings, mappings, aliases.

create_roleC

Create or update a role with specified cluster and index privileges.

Inputs: name (required), cluster, indices, applications, +2 more.

create_userC

Create a new user with specified roles and permissions.

Inputs: username (required), roles (required), password, full_name, +3 more.

delete_indexA

Delete an index. WARNING: This permanently deletes all data in the index.

Inputs: index (required), confirm (required).

delete_roleC

Delete a role from Elasticsearch.

Inputs: name (required).

delete_userA

Delete a user from Elasticsearch. This action cannot be undone.

Inputs: username (required).

esql_queryC

Execute an ES|QL query for data analysis. ES|QL is a piped query language for filtering, transforming, and aggregating data.

Inputs: query (required), format.

get_aliasesC

Get index aliases.

Inputs: index, alias.

get_documentC

Retrieve a specific document by its ID from an index.

Inputs: index (required), id (required), _source.

get_indexB

Get detailed information about a specific index including settings and mappings.

Inputs: index (required).

get_index_statsB

Get statistics for one or more indices including document counts, storage, and operations.

Inputs: index.

get_mappingsC

Get the field mappings for an index.

Inputs: index (required).

get_privilegesB

Get the privileges for the current authenticated user.

Inputs: no named parameters.

get_roleC

Get detailed information about a specific role.

Inputs: name (required).

get_settingsC

Get the settings for an index.

Inputs: index (required), include_defaults.

get_shardsC

Get detailed shard allocation information.

Inputs: index.

get_userB

Get detailed information about a specific user.

Inputs: username (required).

has_privilegesC

Check if the current user has specific cluster or index privileges.

Inputs: cluster, index.

invalidate_api_keyC

Invalidate one or more API keys.

Inputs: ids, name, owner.

list_api_keysB

List API keys. Can filter by owner, name, or realm.

Inputs: owner, name, realm_name.

list_indicesB

List all indices in the cluster with their health, status, and document counts.

Inputs: pattern, health, include_hidden.

list_rolesB

List all roles defined in Elasticsearch.

Inputs: no named parameters.

list_usersB

List all users in the Elasticsearch security realm.

Inputs: no named parameters.

msearchB

Execute multiple search queries in a single request for efficiency.

Inputs: searches (required).

nodes_infoB

Get information about cluster nodes including roles, JVM settings, and plugins.

Inputs: node_id, metric.

nodes_statsB

Get statistics for cluster nodes including CPU, memory, disk, and index operations.

Inputs: node_id, metric.

pending_tasksB

Get a list of pending cluster-level tasks.

Inputs: no named parameters.

refresh_indexC

Refresh an index to make recent changes available for search.

Inputs: index (required).

set_user_enabledC

Enable or disable a user account.

Inputs: username (required), enabled (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 37 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources like indices, users, roles, or cluster operations, with clear boundaries. However, some overlap exists between cluster_info and cluster_stats (both provide cluster information), and between get_index and get_index_stats (both retrieve index details), which could cause minor confusion but descriptions help differentiate them.

    Naming Consistency5/5

    Tool names follow a highly consistent snake_case pattern with clear verb_noun conventions throughout, such as create_index, delete_user, list_roles, and get_document. There are no deviations in naming style, making the set predictable and readable.

    Tool Count3/5

    With 37 tools, the count feels heavy for an Elasticsearch server, bordering on excessive. While Elasticsearch has a broad API surface, this many tools may overwhelm agents and could be streamlined by grouping related operations or omitting less critical ones, though it's not extreme.

    Completeness5/5

    The tool set provides comprehensive coverage of Elasticsearch's core domains, including CRUD operations for indices, documents, users, roles, and API keys, along with cluster management, search, and monitoring. There are no obvious gaps; all major workflows are supported, ensuring agents can handle typical tasks without dead ends.

    Related MCP Connectors