mcp-server-elasticsearch

Unofficial Elasticsearch MCP Server

A production-ready Model Context Protocol (MCP) server that connects AI assistants like Claude Desktop to Elasticsearch clusters. This server provides comprehensive Elasticsearch operations through natural language interactions, featuring advanced configuration management, security controls, and extensive tooling.

This is an enhancement of the Official Elastic MCP Server with the four tools (Core Operations).

🚀 Key Features

• 🔧 Comprehensive Tooling: 60+ Elasticsearch operations including search, indexing, cluster management, and analytics
• ⚙️ Advanced Configuration: Type-safe configuration system with environment variable validation
• 🔒 Security Controls: Read-only mode with strict/warning options for safe production monitoring
• 📊 Rich Search: Advanced search with automatic highlighting, aggregations, and SQL support
• 🔄 Bulk Operations: Efficient bulk indexing, updating, and deletion with helper APIs
• 📈 Cluster Monitoring: Health checks, node statistics, and performance metrics
• 🛡️ Error Handling: Robust error handling with detailed logging and troubleshooting guides
• ⚡ Performance: Built on Bun runtime for optimal performance and modern JavaScript features

📋 Table of Contents

• Prerequisites
• Installation
• Quick Start
• Configuration
• Available Tools
• Usage Examples
• Development
• Architecture
• Security
• Troubleshooting

🔧 Prerequisites

Installing Bun

This project uses Bun as the JavaScript runtime for optimal performance. Install Bun using one of these methods:

macOS/Linux:

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Package Managers:

# npm
npm install -g bun

# Homebrew (macOS)
brew install bun

# Scoop (Windows)
scoop install bun

Verify installation:

bun --version

Other Requirements

• Bun: Latest version (recommended runtime)
• Elasticsearch: Version 7.x or higher (8.x+ recommended)
• MCP Client: Claude Desktop, or any MCP-compatible client
• Node.js: 18+ (for npm compatibility if needed)

📦 Installation

Option 1: Use Published NPM Package (Recommended)

The easiest way to use the Elasticsearch MCP Server:

npx @elastic/mcp-server-elasticsearch

Option 2: Local Development Installation

1. Clone the repository:

   git clone https://github.com/elastic/mcp-server-elasticsearch.git
   cd mcp-server-elasticsearch
   

2. Install dependencies:

   bun install
   

3. Build the project:

   bun run build
   

🚀 Quick Start

1. Configure Your Environment

Create a .env file from the template:

cp .env.example .env

Minimal Configuration:

# Required
ES_URL=http://localhost:9200

# Authentication (choose one)
ES_API_KEY=your_api_key_here
# OR
ES_USERNAME=elastic
ES_PASSWORD=changeme

# Optional: Enable read-only mode for safety
READ_ONLY_MODE=false
LOG_LEVEL=info

2. Validate Configuration

# Basic validation
bun run validate-config

# Full validation with connection test
bun run validate-config:full

3. Configure MCP Client (Claude Desktop)

Add to your MCP client configuration:

For Published Package:

{
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": ["-y", "@elastic/mcp-server-elasticsearch"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "bun",
      "args": ["run", "/path/to/your/project/src/index.ts"],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_API_KEY": "your-api-key"
      }
    }
  }
}

4. Start Using

Open your MCP client and start asking questions about your Elasticsearch data:

• "What indices do I have in my cluster?"
• "Show me the field mappings for the products index"
• "Find all orders over $500 from last month"

⚙️ Configuration

This server features a comprehensive configuration system with type-safe validation and environment variable support.

Environment Variables

Required Variables

Authentication (Choose One Method)

API Key Authentication (Recommended):

ES_API_KEY=your_api_key_here

Username/Password Authentication:

ES_USERNAME=your_username
ES_PASSWORD=your_password

Server Configuration

Elasticsearch Configuration

Logging Configuration

Configuration Examples

Local Development

ES_URL=http://localhost:9200
LOG_LEVEL=debug
READ_ONLY_MODE=false

Production with API Key

ES_URL=https://your-cluster.es.cloud.aws.com:443
ES_API_KEY=your_production_api_key
READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true
LOG_LEVEL=info
ES_MAX_RETRIES=5
ES_REQUEST_TIMEOUT=60000

Elastic Cloud

ES_URL=https://your-deployment.es.us-central1.gcp.cloud.es.io:443
ES_API_KEY=your_cloud_api_key
READ_ONLY_MODE=true
LOG_LEVEL=info

Self-Hosted with TLS

ES_URL=https://elasticsearch.company.com:9200
ES_USERNAME=mcp_user
ES_PASSWORD=secure_password
ES_CA_CERT=/etc/ssl/certs/elasticsearch-ca.pem
READ_ONLY_MODE=true
LOG_LEVEL=warn

Read-Only Mode

The server supports read-only mode for safe operations in production:

Strict Mode (Production)

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=true

• Blocks all destructive operations
• Returns error responses for write/delete operations
• Perfect for monitoring and analytics

Warning Mode (Development)

READ_ONLY_MODE=true
READ_ONLY_STRICT_MODE=false

• Allows operations with prominent warnings
• Logs warnings for destructive operations
• Great for testing and controlled environments

🛠️ Available Tools

Core Operations

• list_indices - List all available Elasticsearch indices
• get_mappings - Get field mappings for indices
• search - Perform searches with automatic highlighting
• get_shards - Get shard information and distribution

Document Operations

• get_document - Retrieve documents by ID
• index_document - Create or update documents (Write Operation)
• update_document - Update existing documents (Write Operation)
• delete_document - Delete documents (Destructive Operation)
• document_exists - Check if documents exist

Bulk Operations

• bulk_operations - Efficient bulk create/update/delete (Write/Destructive Operation)
• multi_get - Retrieve multiple documents

Search & Analytics

• execute_sql_query - Execute SQL queries
• count_documents - Count matching documents
• scroll_search - Handle large result sets
• multi_search - Execute multiple searches
• update_by_query - Bulk document updates (Write Operation)
• delete_by_query - Bulk document deletion (Destructive Operation)
• clear_scroll - Clear scroll contexts to free resources

Index Management

• create_index - Create new indices (Write Operation)
• delete_index - Delete indices (Destructive Operation)
• index_exists - Check index existence
• get_index - Get index information
• get_index_settings - Get index settings
• update_index_settings - Modify index settings (Write Operation)
• put_mapping - Update index mappings (Write Operation)
• refresh_index - Force index refresh (Write Operation)
• flush_index - Force index flush (Write Operation)
• reindex_documents - Copy/move data between indices (Write Operation)

Template Management

• search_template - Execute stored search templates
• multi_search_template - Execute multiple search templates
• get_index_template - Get index template definitions
• put_index_template - Create or update index templates (Write Operation)
• delete_index_template - Delete index templates (Destructive Operation)

Analytics & Term Analysis

• get_term_vectors - Get term vectors for documents
• get_multi_term_vectors - Get term vectors for multiple documents

Index Aliases

• get_aliases - Get index aliases
• put_alias - Create index aliases (Write Operation)
• delete_alias - Delete index aliases (Destructive Operation)
• update_aliases - Update multiple aliases atomically (Write Operation)

Cluster Management

• get_cluster_health - Cluster health status
• get_cluster_stats - Cluster statistics
• get_nodes_info - Node information
• get_nodes_stats - Node statistics

Field Mapping & SQL Management

• get_field_mapping - Get specific field mappings
• clear_sql_cursor - Clear SQL cursors
• translate_sql_query - Convert SQL to Elasticsearch DSL

Index Lifecycle Management (ILM)

• ilm_get_lifecycle - Get lifecycle policies
• ilm_put_lifecycle - Create or update lifecycle policies (Write Operation)
• ilm_delete_lifecycle - Delete lifecycle policies (Destructive Operation)
• ilm_explain_lifecycle - Explain lifecycle state of indices
• ilm_get_status - Get ILM status
• ilm_start - Start ILM plugin (Write Operation)
• ilm_stop - Stop ILM plugin (Write Operation)
• ilm_retry - Retry failed lifecycle steps (Write Operation)
• ilm_remove_policy - Remove policies from indices (Write Operation)
• ilm_move_to_step - Manually move index to lifecycle step (Destructive Operation)
• ilm_migrate_to_data_tiers - Migrate to data tiers (Destructive Operation)

Enrich Policies

• enrich_get_policy - Get enrich policy information
• enrich_put_policy - Create enrich policies (Write Operation)
• enrich_delete_policy - Delete enrich policies (Destructive Operation)
• enrich_execute_policy - Execute enrich policies (Write Operation)
• enrich_stats - Get enrich statistics

💡 Usage Examples

Natural Language Queries

"What indices do I have in my cluster?"
"Show me the field mappings for the 'products' index"
"Count how many documents are in the logs index"
"What's the health status of my cluster?"

Complex Search Examples

"Search for users with email containing 'gmail' in the users index"
"Find all error logs from the last 24 hours with severity high"
"Show me products with price between 100 and 500 sorted by popularity"
"Get aggregated sales data grouped by region and month"

Administrative Operations

"Create a new index called 'user-analytics' with timestamp mapping"
"Show me the cluster health and node information"
"List all indices that haven't been accessed in the last week"
"Update the refresh interval for the logs index to 30 seconds"

🔨 Development

Available Scripts

# Development
bun run dev                    # Start in development mode
bun run build                  # Build for production
bun run start                  # Start built server

# Configuration Management
bun run validate-config        # Validate configuration
bun run validate-config:full   # Full validation + connection test
bun run test-connection        # Test Elasticsearch connection

# Quality & Testing
bun run test                   # Run tests
bun run lint                   # Lint code
bun run format                 # Format code

# Debugging
bun run inspector              # Start MCP inspector for debugging

Development Setup

1. Clone and setup:

   git clone <repository>
   cd mcp-server-elasticsearch
   bun install
   

2. Create development environment:

   cp .env.example .env.dev
   # Edit .env.dev with your local settings
   

3. Start development server:

   bun run dev
   

4. Debug with MCP Inspector:

   ES_URL=your-url ES_API_KEY=your-key bun run inspector
   

   Open http://localhost:5173 for the inspector interface.

Testing Configuration

# Test configuration validity
bun run validate-config

# Test with connection verification
bun run validate-config:full --check-connection

# Show all configuration details
bun run validate-config --show-all

🏗️ Architecture

Project Structure

src/
├── config.ts              # Centralized configuration system
├── index.ts               # Entry point and server startup
├── server.ts               # MCP server creation and setup
├── validation.ts           # Environment and connection validation
├── tools/                  # Tool implementations
│   ├── index.ts           # Tool registration
│   ├── core/              # Core operations (search, list, mappings)
│   ├── document/          # Document operations
│   ├── search/            # Advanced search operations
│   ├── index_management/  # Index management tools
│   ├── cluster/           # Cluster monitoring tools
│   ├── bulk/              # Bulk operations
│   ├── analytics/         # Analytics and term vectors
│   ├── alias/             # Index alias management
│   ├── template/          # Template management
│   ├── advanced/          # Advanced operations
│   ├── mapping/           # Field mapping tools
│   ├── ilm/               # Index Lifecycle Management
│   └── enrich/            # Enrich policies
└── utils/
    ├── logger.ts          # MCP-compatible logging system
    └── readOnlyMode.ts    # Read-only mode management

Configuration System

The server uses a sophisticated configuration system:

• Type Safety: Full TypeScript support with Zod schemas
• Environment First: Configuration via environment variables
• Validation: Automatic validation at startup
• Layered: Defaults → Environment Variables → Validation
• Documentation: Self-documenting with clear examples

Read-Only Mode Implementation

• Operation Classification: Tools categorized by destructive potential
• Flexible Modes: Strict blocking vs. warning modes
• Granular Control: Per-operation type checking
• Logging Integration: Comprehensive audit trails

🔒 Security

Best Practices

1. Use API Keys: Prefer API key authentication over username/password
2. Principle of Least Privilege: Create dedicated API keys with minimal permissions
3. Read-Only Production: Enable read-only mode for production monitoring
4. Network Security: Use TLS/SSL for connections
5. Credential Management: Keep credentials in environment variables

Creating Secure API Keys

POST /_security/api_key
{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["index-1", "index-2", "index-pattern-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}

Read-Only Mode Operations

Always Protected (Destructive):

• delete_document, delete_index, delete_by_query
• delete_alias, delete_index_template

Protected (Write/Modify):

• index_document, update_document, bulk_operations
• create_index, update_index_settings, put_mapping

Always Allowed (Read-Only):

• search, get_document, list_indices
• get_mappings, count_documents, get_cluster_health

🔍 Troubleshooting

Common Issues

Configuration Errors

Invalid URL Format:

Error: ES_URL is not a valid URL format

Solution: Ensure URL includes protocol: http:// or https://

Missing Authentication:

Error: Either ES_API_KEY or both ES_USERNAME and ES_PASSWORD must be provided

Solution: Provide complete authentication credentials

Connection Issues

Connection Refused:

Error: ECONNREFUSED

Solution: Verify Elasticsearch is running and URL is correct

SSL/TLS Issues:

Error: certificate verify failed

Solution: Use ES_CA_CERT or verify certificate configuration

Authentication Failed:

Error: 401 Unauthorized

Solution: Verify API key or username/password are correct

Read-Only Mode

Operations Blocked:

🚫 READ-ONLY MODE: DESTRUCTIVE DELETE operation blocked

Solution: Set READ_ONLY_MODE=false or use read-only operations only

Debug Mode

Enable debug logging for detailed troubleshooting:

LOG_LEVEL=debug bun run dev

Validation Tools

# Check configuration
bun run validate-config

# Test connection
bun run validate-config:full

# Test specific operations
bun run test-connection

MCP Inspector

For debugging MCP protocol issues:

bun run inspector

Open http://localhost:6274 to inspect MCP communication.

Development Workflow

1. Fork and clone the repository
2. Create a feature branch from main
3. Make your changes with tests
4. Run quality checks:

   bun run lint
   bun run format
   bun run test
   bun run validate-config
   

5. Submit a pull request with clear description

Code Standards

• TypeScript: Strict type checking enabled
• ESLint: Code linting with provided configuration
• Prettier: Code formatting with provided configuration
• Zod: Schema validation for configuration
• Testing: Comprehensive test coverage required

📄 License

This project is licensed under the Apache License 2.0. See for details.

🔗 Links

• Model Context Protocol
• Elasticsearch Documentation
• Bun Runtime
• Claude Desktop

📈 Performance

Built on Bun runtime for optimal performance:

• Fast Startup: Rapid server initialization
• Memory Efficient: Optimized memory usage
• Modern JavaScript: Latest ECMAScript features
• Native TypeScript: No compilation overhead in development

Need Help? Check our troubleshooting guide for common solutions.