sansong089/elasticsearch-mcp-server

Elasticsearch MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Elasticsearch maintenance and management capabilities. Supports cluster monitoring, index management, snapshot operations, alias management, and document operations through a unified interface.

|

Features

🔍 Cluster Management

• Health Check: Monitor cluster health status
• Statistics: Get comprehensive cluster statistics

💾 Snapshot Management

• Create Snapshots: Backup indices to snapshot repositories
• Restore Snapshots: Restore indices from backups
• Repository Management: Create and manage snapshot repositories

📊 Index Operations

• Index Listing: List all indices with filtering
• Index Cleanup: Remove old indices based on patterns and age
• Index Optimization: Force merge segments for better performance
• Reindexing: Migrate data between indices with optional filtering

🏷️ Template Management

• Create Templates: Define index templates for new indices
• Template Operations: View, update, and delete templates

🔗 Alias Management

• Alias Operations: Create, view, delete, and switch aliases
• Alias-Based Operations: Perform document operations using aliases

📝 Document Operations

• Query Documents: Search and retrieve documents with flexible queries
• Update Documents: Modify documents using update scripts
• Delete Documents: Remove documents based on queries or IDs
• Alias-Based Document Ops: All document operations support aliases

🚀 Installation & Configuration

📋 System Requirements

• Node.js: 16.0 or higher
• Elasticsearch: 7.x or 8.x

📦 Installation Steps

# Clone the repository
git clone https://github.com/sansong089/elasticsearch-mcp-server.git
cd elasticsearch-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

⚙️ Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\elasticsearch-mcp-server\\build\\server\\index.js"],
      "env": {
        "ES_HOST": "localhost",
        "ES_PORT": "9200",
        "ES_SCHEME": "http",
        "ES_USERNAME": "your_username",
        "ES_PASSWORD": "your_password"
      }
    }
  }
}

Cline

Add to your Cline MCP settings:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["/path/to/your/elasticsearch-mcp-server/build/server/index.js"],
      "env": {
        "ES_HOST": "localhost",
        "ES_PORT": "9200",
        "ES_SCHEME": "http",
        "ES_USERNAME": "your_username",
        "ES_PASSWORD": "your_password"
      }
    }
  }
}

Note: Replace the path with the actual path to your build/server/index.js file after building the project.

🔧 Available Tools

This project primarily supports Elasticsearch maintenance and management. The server provides the following MCP tools:

Cluster Management

• check_cluster_health - Check cluster health status
• get_cluster_stats - Get cluster statistics

Snapshot Operations

• create_snapshot - Create index snapshots
• restore_snapshot - Restore from snapshots
• create_snapshot_repository - Create snapshot repositories

Index Maintenance

• list_indices - List indices
• cleanup_old_indices - Clean up old indices
• optimize_indices - Optimize indices
• reindex_data - Reindex data

Template Management

• create_index_template - Create index templates
• get_index_template - View templates
• delete_index_template - Delete templates
• list_index_templates - List all templates

Alias Management

• create_index_alias - Create aliases
• get_index_alias - View aliases
• delete_index_alias - Delete aliases
• list_aliases - List all aliases
• switch_index_alias - Switch aliases between indices

Document Operations (Index-based)

• query_index_docs - Query documents in indices
• update_documents - Update documents by query
• delete_documents - Delete documents by query
• update_document_by_id - Update single document
• delete_document_by_id - Delete single document

Document Operations (Alias-based)

• query_alias_docs - Query documents via aliases
• update_alias_docs - Update documents via aliases
• delete_alias_docs - Delete documents via aliases
• update_alias_doc_by_id - Update document via alias
• delete_alias_doc_by_id - Delete document via alias

Index Information

• get_index_mapping - Get index mappings
• get_index_stats - Get index statistics

Example Usage

Creating a Snapshot

{
  "repository": "my_backup_repo",
  "snapshot": "daily_backup_2024",
  "indices": "logstash-*"
}

Querying Documents

{
  "index": "my_index",
  "query": "{\"match\": {\"status\": \"active\"}}",
  "size": 50
}

Creating an Alias

{
  "alias": "current_data",
  "indices": "data-2024-09-*",
  "filter": "{\"range\": {\"timestamp\": {\"gte\": \"now-30d\"}}}"
}

⚠️ Important Disclaimer

Critical Warning: Modification and deletion operations must NEVER be authorized for automatic execution by AI assistants

Please read the following terms carefully:

1. Usage Restrictions

   • This software is for learning, development, and testing purposes only
   • Do not use in unauthorized production environments

2. Risk Warnings

   • Users must bear all consequences of operations themselves
   • Including but not limited to data loss, service interruption, etc.

3. Security Warnings

   • Modification and deletion operations must NEVER be authorized for automatic execution by AI assistants
   • All destructive operations must go through manual confirmation and review
   • Operations with Confluence administrative privileges may cause serious security risks
   • Please run in secure and controllable environments

4. Disclaimer

   • This project is provided "as is" without any express or implied warranties
   • The author is not responsible for any damages caused by using this software

Please ensure you understand and accept the above terms before use.