Elastic MCP Server
Provides a comprehensive set of tools for security management, search operations, index management, and cluster monitoring within an Elasticsearch instance, allowing for management of users, roles, API keys, and execution of complex queries.
Provides a comprehensive set of tools for security management, search operations, index management, and cluster monitoring within an Elasticsearch instance, allowing for management of users, roles, API keys, and execution of complex queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Elastic MCP Server show me the health status of my elasticsearch cluster"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 install2. 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 .envEdit .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-key3. Build
npm run build4. Run
npm startConfiguration
Environment Variables
Variable | Required | Description |
| Yes | Elasticsearch cluster URL |
| Yes* | Pre-encoded API key (base64) |
| Yes* | API key ID (alternative to encoded) |
| Yes* | API key secret (use with ID) |
| Yes* | Basic auth username |
| Yes* | Basic auth password |
| No | Skip SSL verification (default: false) |
| No | Request timeout in ms (default: 30000) |
| 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_N0o0HkABasic Auth (Not Recommended)
ELASTIC_USERNAME=elastic
ELASTIC_PASSWORD=your-passwordAvailable Tools
Search Tools (5 tools)
Tool | Description |
| Execute search queries using Elasticsearch Query DSL |
| Execute ES|QL queries for data analysis |
| Retrieve a specific document by ID |
| Count documents matching a query |
| Execute multiple search queries in one request |
Security Tools (12 tools)
Tool | Description |
| List all users in the security realm |
| Get detailed user information |
| Create a new user with roles |
| Delete a user |
| Enable or disable a user |
| List all defined roles |
| Get role details |
| Create or update a role |
| Delete a role |
| List API keys |
| Create a new API key |
| Invalidate API keys |
| Get current user privileges |
| Check specific privileges |
| Get current authenticated user info |
Index Tools (9 tools)
Tool | Description |
| List all indices with health and stats |
| Get index details |
| Get field mappings |
| Get index settings |
| Create a new index |
| Delete an index (requires confirmation) |
| Refresh an index |
| Get index statistics |
| Get index aliases |
Cluster Tools (8 tools)
Tool | Description |
| Get cluster health status |
| Get comprehensive cluster statistics |
| Get basic cluster info and version |
| Get node information |
| Get node statistics |
| List pending cluster tasks |
| Explain shard allocation |
| 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 testRun Tests with Coverage
npm run test:coverageLint
npm run lintWatch Mode
npm run devClaude 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 workEnsure Node.js is installed and available in your PATH
Run
npm installandnpm run buildbefore 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_indextool requires explicit confirmationCreated API keys return the encoded value but not the raw secret
License
MIT
Available Tools
37 toolsallocation_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).
searchC
Execute a search query using Elasticsearch Query DSL. Supports full-text search, filters, aggregations, and sorting.
Inputs: index (required), query, size, from, +3 more.
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
Scored across 37 tools
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.
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.
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.
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
Search multiple indices, index data, and get personalized recommendations
Graph-vector database: run Helix queries, read query insights and health, manage databases
Serverless hybrid search: full-text, vector and faceted search, in SQL, ES DSL, Solr and more.
Search log events, investigate anomalies, and manage cases in your Knowledge Grid tenant.