Custom Elasticsearch MCP Server

A simple MCP (Model Context Protocol) server for Elasticsearch designed for cloud environments where your public key is already authorized on the server.

Why This Custom Version?

No API Key Required - Unlike the official Elasticsearch MCP server that requires both ES_URL and ES_API_KEY, this version only needs the URL since your public key is already trusted on the cloud server.

Enhanced Tools - Better usability with optional parameters and improved defaults compared to the official version.

What This Does

This MCP server connects Cursor to your Elasticsearch cluster with 4 powerful tools:

• list_indices - List all indices (optional pattern filter)

• search - Full Elasticsearch Query DSL support

• get_mappings - Get field mappings for any index

• get_shards - View cluster shard information

Quick Start

Build from Source

git clone https://github.com/M0-AR/Custom-Elasticsearch-MCP-Server.git
cd Custom-Elasticsearch-MCP-Server
docker build -t elasticsearch-mcp:latest .

2. Add to Cursor MCP Configuration

Add this to your .cursor/mcp.json file:

Configuration:

{
    "mcpServers": {
        "elasticsearch-custom": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--add-host=host.docker.internal:host-gateway",
                "-e",
                "ES_URL=http://host.docker.internal:9400",
                "elasticsearch-mcp:latest"
            ]
        }
    }
}

3. Restart Cursor

Close and reopen Cursor. You should see the elasticsearch-custom server with 4 tools enabled.

Configuration

Environment Variables:

• ES_URL - Your Elasticsearch URL (default: http://localhost:9400)

• MAX_CONNECTIONS - Maximum concurrent connections (default: 100)

• MAX_KEEPALIVE_CONNECTIONS - Maximum keepalive connections (default: 20)

• CONNECTION_TIMEOUT - Connection timeout in seconds (default: 30)

• REQUEST_TIMEOUT - Request timeout in seconds (default: 30)

For different Elasticsearch ports:

"ES_URL=http://host.docker.internal:9200"

For high-traffic environments:

"MAX_CONNECTIONS=200",
"MAX_KEEPALIVE_CONNECTIONS=50",
"CONNECTION_TIMEOUT=60",
"REQUEST_TIMEOUT=60"

Example Usage

Once connected in Cursor, you can:

• List all indices: "Show me all elasticsearch indices"

• Search data: "Search for sales data in hq.sales index"

• Get mappings: "What fields are in the hq.menuitems index?"

• Check cluster: "Show me the elasticsearch cluster status"

Comparison with Official Server

Concurrent Request Handling

This MCP server is designed to handle multiple parallel requests from multiple applications simultaneously using industry best practices:

Key Features:

✅ Async/Await Architecture - Non-blocking I/O for parallel request processing ✅ Connection Pooling - Reuses HTTP connections (up to 100 concurrent) ✅ HTTP/2 Support - Multiplexes multiple requests over single connection ✅ Configurable Limits - Adjust connection limits for your workload ✅ Thread-Safe - FastMCP handles concurrent tool execution safely

Performance Characteristics:

• Default: 100 concurrent connections, 20 keepalive connections

• Scalable: Configure up to 1000+ concurrent connections

• Efficient: Connection reuse reduces latency by ~50%

• Reliable: Proper timeout handling prevents connection exhaustion

Configuration for High Traffic:

{
    "mcpServers": {
        "elasticsearch-custom": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--add-host=host.docker.internal:host-gateway",
                "-e", "ES_URL=http://host.docker.internal:9400",
                "-e", "MAX_CONNECTIONS=200",
                "-e", "MAX_KEEPALIVE_CONNECTIONS=50",
                "-e", "CONNECTION_TIMEOUT=60",
                "-e", "REQUEST_TIMEOUT=60",
                "elasticsearch-mcp:latest"
            ]
        }
    }
}

Testing Concurrent Requests:

# Test 10 parallel requests
for i in {1..10}; do
    echo '{"jsonrpc": "2.0", "id": '$i', "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}' | \
    python3 simple_elasticsearch_mcp.py &
done
wait

Files

• simple_elasticsearch_mcp.py - Main MCP server

• Dockerfile - Container build instructions

• requirements.txt - Python dependencies

Manual Testing

Test the server directly:

python3 simple_elasticsearch_mcp.py

Test with JSON-RPC commands:

1. List all tools:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python3 simple_elasticsearch_mcp.py

2. List all indices:

echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}' | python3 simple_elasticsearch_mcp.py

3. Search for data:

echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search", "arguments": {"index": "hq.sales", "queryBody": {"query": {"match_all": {}}, "size": 3}}}}' | python3 simple_elasticsearch_mcp.py

4. Get index mappings:

echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_mappings", "arguments": {"index": "hq.menuitems"}}}' | python3 simple_elasticsearch_mcp.py

5. Check cluster shards:

echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "get_shards", "arguments": {}}}' | python3 simple_elasticsearch_mcp.py

Set custom Elasticsearch URL:

ES_URL="http://your-es-host:9200" python3 simple_elasticsearch_mcp.py

Troubleshooting

❌ "Connection refused" or "timed out" errors

Root Cause: The most common issue is Docker container networking when Elasticsearch is accessible via SSH tunnel.

Solution: Ensure these requirements are met:

1. SSH Tunnel Must Be Active

If your Elasticsearch is behind SSH tunnel (common for cloud deployments):

# Start SSH tunnel to forward port 9400
ssh -L 9400:localhost:9400 -N -f -l username your-server-ip

# Verify tunnel is working
curl -X GET "localhost:9400/_cluster/health?pretty"

2. Correct Docker Configuration

Your mcp.json should use exactly this configuration:

"elasticsearch-custom": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ES_URL=http://host.docker.internal:9400",
        "elasticsearch-mcp:latest"
    ]
}

Key Points:

• ✅ Use --add-host=host.docker.internal:host-gateway (not IP addresses)

• ✅ Use ES_URL=http://host.docker.internal:9400 (not localhost)

• ✅ SSH tunnel must be running before starting Cursor

3. Test Docker Connectivity

# Test if Docker can reach your Elasticsearch
docker run --rm --add-host=host.docker.internal:host-gateway alpine/curl \
  curl -s http://host.docker.internal:9400/_cluster/health

4. Complete MCP Docker Test

Test the full MCP workflow with this comprehensive command:

# Full MCP server test with proper initialization
{
    echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}';
    echo '{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}';
    echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}';
} | docker run -i --rm --add-host=host.docker.internal:host-gateway -e ES_URL="http://host.docker.internal:9400" elasticsearch-mcp:latest

Expected Output:

• Initialization response with server info

• List of all Elasticsearch indices in JSON format

• No error messages

5. Alternative: Network Host Mode

If host-gateway doesn't work, try network host mode:

"args": [
    "run", "-i", "--rm", "--network=host",
    "-e", "ES_URL=http://localhost:9400",
    "elasticsearch-mcp:latest"
]

❌ "Received request before initialization was complete"

Root Cause: MCP protocol requires proper initialization sequence.

Solution: Always initialize before calling tools:

# Correct sequence:
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}'
echo '{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}'
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_indices", "arguments": {}}}'

That's It!

Build → Add to config → Restart Cursor → Done! 🚀