tdupur/elastic-mcp-demo

Elasticsearch Cloud MCP Server (w ECH deployment)

A comprehensive Model Context Protocol (MCP) server that provides seamless integration with Elasticsearch Cloud, enabling powerful search, analysis, and cluster management capabilities through natural language interactions.

🌟 Features

• Complete Elasticsearch Cloud Integration - Connect securely using Cloud ID and API keys
• Advanced Search Capabilities - Perform complex queries using Elasticsearch DSL
• ES|QL Support - Execute modern Elasticsearch Query Language queries
• Cluster Health Monitoring - Real-time cluster status and performance metrics
• Index Management - Comprehensive index analysis, mappings, and shard information
• Text Analysis - Leverage Elasticsearch analyzers for text processing
• Intelligent Prompts - Pre-built prompts for common operations and troubleshooting
• Secure Configuration - Environment-based configuration with fallback options

🏗️ Architecture

This MCP server is built using the FastMCP framework and provides:

• 8 Resources - Real-time cluster and index information
• 7 Tools - Interactive operations for search and management
• 6 Prompts - Guided workflows for common tasks

📋 Prerequisites

• Python 3.8 or higher
• Elasticsearch Cloud deployment
• Valid Elasticsearch Cloud credentials (API key or username/password)

🚀 Quick Start

1. Clone the Repository

git clone <your-repository-url>
cd <repository-name>

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

Create a .env file in the project root:

# Required: Elasticsearch Cloud Configuration
ELASTIC_CLOUD_ID=your_cloud_id_here

# Authentication (choose one method)
# Option 1: API Key (Recommended)
ELASTIC_API_KEY=your_api_key_here

# Option 2: Username/Password
# ELASTIC_USERNAME=your_username
# ELASTIC_PASSWORD=your_password

# Optional: Connection Settings
ELASTIC_TIMEOUT=60
ELASTIC_MAX_RETRIES=3
ELASTIC_RETRY_ON_TIMEOUT=true

4. Test Your Server with MCP Inspector

Before connecting to Claude Desktop, it's essential to test your MCP server using the built-in MCP Inspector tool. This web-based debugging interface allows you to validate all Resources, Tools, and Prompts interactively.

Starting the Inspector

In your terminal with the project directory active, run:

mcp dev elasticsearch_mcp_server.py

The first time you run this command, MCP may request permission to install the Inspector's web components. Type y and press Enter to proceed.

The tool will start a local proxy server and automatically open the MCP Inspector interface in your web browser at http://127.0.0.1:6274.

Authentication Note: Recent MCP Inspector versions may require authentication. If the browser doesn't open automatically, look for a message in your terminal like:

MCP Inspector available at: http://127.0.0.1:6274?token=abc123...

Use the complete URL with the token to access the Inspector securely.

Using the Inspector Interface

1. Connection Verification

• When the page loads, it automatically connects to your running server
• The status indicator changes from "disconnected" to "Restart | Disconnect"
• The History panel shows an initialize event

2. Exploring Your Server Capabilities

Navigate through the three main tabs:

Resources Tab:

• Click "List Resources" to see all available data endpoints
• Test resources like:
  • elasticsearch://cluster/health - Current cluster status
  • elasticsearch://indices/overview - Index summary
  • elasticsearch://cluster/stats - Comprehensive statistics

Tools Tab:

• Click "List Tools" to view all interactive functions
• Test tools such as:
  • list_indices - Browse available indices
  • search - Execute Elasticsearch queries
  • cluster_health - Get health information
  • get_mappings - Examine index structure

Prompts Tab:

• View pre-built prompt templates
• Test prompts like:
  • elasticsearch_health_check - Comprehensive analysis workflow
  • index_analysis - Detailed index examination
  • search_performance_analysis - Performance optimization guidance

3. Running Test Operations

Testing a Simple Tool:

1. Navigate to the Tools tab
2. Select cluster_health from the list
3. Click "Run Tool" (no parameters needed)
4. Review the JSON response for cluster status information

Testing a Parameterized Tool:

1. Select search from the Tools list
2. Fill in the required parameters:

   {
     "index": "your-index-name",
     "query": {
       "match_all": {}
     },
     "size": 5
   }
   

3. Click "Run Tool"
4. Verify the search results in the response panel

Testing Resources:

1. Go to the Resources tab
2. Select any resource (e.g., elasticsearch://cluster/info)
3. Click "Read Resource"
4. Examine the returned cluster information

Validation Checklist

Use the Inspector to verify:

• ✅ All 8 resources return data without errors
• ✅ All 7 tools execute successfully with valid parameters
• ✅ Error handling works with invalid inputs
• ✅ Elasticsearch connection is established correctly
• ✅ Authentication credentials are working
• ✅ Response formats are consistent and readable

Stopping the Test Server

After validating your server functionality:

1. Return to the terminal running mcp dev
2. Press Ctrl+C to stop the development server
3. The MCP Inspector will disconnect automatically

5. Install in Claude Desktop

Once your server passes all Inspector tests, install it in Claude Desktop for production use:

mcp install elasticsearch_mcp_server.py --name "Elasticsearch Cloud MCP"

Verify Installation

Check that the installation worked by viewing the Claude Desktop configuration:

macOS:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

type %APPDATA%\Claude\claude_desktop_config.json

You should see your server listed under the mcpServers section:

{
  "mcpServers": {
    "Elasticsearch Cloud MCP": {
      "command": "python",
      "args": ["path/to/elasticsearch_mcp_server.py"],
      "env": {
        "ELASTIC_CLOUD_ID": "your_cloud_id",
        "ELASTIC_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Required

Important: Restart Claude Desktop after installation to load the new MCP server configuration. The server will automatically start when Claude Desktop opens.

6. Start Chatting with your MCP Client (in this example Claude Desktop)

With your Elasticsearch MCP server properly installed and Claude Desktop restarted, you can now interact with your Elasticsearch data using natural language. The power of this integration becomes apparent when you realize that Claude can now understand the structure of your data, execute complex queries, and present results in meaningful ways.

When you open Claude Desktop, your MCP server will automatically start in the background and establish a connection to your Elasticsearch cluster. You'll notice that Claude now has access to real-time information about your indices, can perform searches, and can analyze your data through the tools and resources you've configured.

Here are some example queries you can try to test the full capabilities of your Elasticsearch MCP integration:

• "Show me all orders over $500 from February 2025"

• "Give me the total size of all of my indices combined as of this moment in time and provide me the aggregate sum in Gb. I just need the sum, a single number, in a visual masonry tile."

These examples demonstrate how natural language queries are transformed into sophisticated Elasticsearch operations. The first query showcases the search capabilities, where Claude will construct the appropriate Elasticsearch query to filter documents based on your criteria. The second example illustrates how Claude can aggregate data across multiple indices and present the results in a specific visual format, demonstrating the seamless integration between data retrieval and presentation.

As you explore these interactions, you'll discover that Claude can not only retrieve data but also analyze patterns, suggest optimizations, and help you understand the health and performance characteristics of your Elasticsearch deployment. The MCP bridge enables this sophisticated interaction without requiring you to understand Elasticsearch Query DSL or complex API calls.

📁 Project Structure

├── elasticsearch_mcp_server.py  # Main MCP server implementation
├── requirements.txt             # Python dependencies
├── .env                        # Environment configuration (create this)
├── .env.example               # Environment template
├── .gitignore                 # Git ignore rules
├── config/                    # Optional configuration directory
│   └── elasticsearch.json    # Alternative JSON configuration
└── README.md                  # This file

⚙️ Configuration

Environment Variables

⚠️ Authentication: You must provide either ELASTIC_API_KEY OR both ELASTIC_USERNAME and ELASTIC_PASSWORD.

Alternative Configuration

You can also use a JSON configuration file at config/elasticsearch.json:

{
  "cloud_id": "your_cloud_id",
  "api_key": "your_api_key",
  "timeout": 60,
  "max_retries": 3,
  "retry_on_timeout": true
}

Environment variables take precedence over the JSON configuration.

🛠️ Available Tools

Core Operations

• list_indices - List all Elasticsearch indices with filtering options
• get_mappings - Retrieve field mappings and index metadata
• search - Execute Elasticsearch DSL queries with full feature support
• esql - Run ES|QL queries for modern data analysis

Analysis & Monitoring

• cluster_health - Get comprehensive cluster health information
• get_shards - Analyze shard distribution and status
• analyze_text - Process text using Elasticsearch analyzers

📊 Resources

Access real-time information about your Elasticsearch deployment:

• elasticsearch://cluster/info - General cluster information
• elasticsearch://cluster/health - Current health status
• elasticsearch://cluster/stats - Comprehensive statistics
• elasticsearch://indices/overview - Index summary and metrics
• elasticsearch://nodes/info - Node information
• elasticsearch://templates/index - Index templates
• elasticsearch://aliases - Index aliases

🎯 Intelligent Prompts

Pre-built prompts for common workflows:

• elasticsearch_health_check - Comprehensive cluster health analysis
• index_analysis - Detailed index examination
• search_performance_analysis - Performance optimization guidance
• data_distribution_analysis - Shard and node distribution review
• semantic_search_setup - ELSER semantic search configuration
• troubleshoot_query - Query optimization and troubleshooting

💡 Usage Examples

Basic Search Query

# Search for documents in the "logs" index
{
  "index": "logs",
  "query": {
    "match": {
      "message": "error"
    }
  },
  "size": 10
}

ES|QL Query

FROM logs
| WHERE @timestamp > NOW() - 1 hour
| STATS count(*) BY level
| SORT count DESC

Health Check Workflow

1. Use the elasticsearch_health_check prompt
2. Review cluster status with cluster_health tool
3. Analyze specific indices with get_mappings
4. Check shard distribution with get_shards

🔒 Security Best Practices

• Never commit your .env file - It contains sensitive credentials
• Use API keys instead of username/password when possible
• Rotate API keys regularly for enhanced security
• Limit API key permissions to only required operations
• Monitor access logs in your Elasticsearch Cloud deployment

🐛 Troubleshooting

Common Issues

Connection Failed

• Verify your ELASTIC_CLOUD_ID is correct
• Check your authentication credentials
• Ensure your IP is whitelisted in Elasticsearch Cloud

Index Not Found

• Confirm the index name spelling
• Check if the index exists using list_indices
• Verify you have access permissions

Query Timeout

• Increase ELASTIC_TIMEOUT value
• Optimize your query for better performance
• Consider using pagination for large result sets

Authentication Error

• Verify API key is valid and not expired
• Check if API key has required permissions
• Try username/password authentication as fallback

Logging

The server includes comprehensive logging. Set log level in your environment:

export PYTHONPATH="."
python -c "import logging; logging.basicConfig(level=logging.DEBUG)"
python elasticsearch_mcp_server.py

📚 References

This project builds upon excellent resources from the Elasticsearch community:

• Model Context Protocol with Elasticsearch - Original MCP integration guide
• Building MCP Servers - Comprehensive MCP architecture tutorial
• Elastic MCP Server Repository - Reference implementation
• Apple Health MCP Example - MCP architecture foundation

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

For questions and support:

1. Check the troubleshooting section
2. Review the Elasticsearch documentation
3. Open an issue in this repository
4. Visit Elastic Community for community support

Built with ❤️ using FastMCP and Elasticsearch