AnilPuram/apache-druid-mcp-server

Apache Druid MCP Server

Model Context Protocol (MCP) server for Apache Druid - provides tools and resources for querying and managing Druid datasources through Claude Desktop, VS Code, and other MCP clients.

Features

• 🔍 Execute SQL queries against Apache Druid
• 📊 List and explore datasources
• 📋 Get detailed metadata including schema, segments, and size information
• 🔗 Test Druid cluster connectivity
• 🚀 Multiple transport protocols: stdio (default) and Server-Sent Events (SSE)
• 🐳 Docker support via published image

Quick Start

NPX (Recommended)

npx apache-druid-mcp

Docker

# Run with SSE transport
docker run -p 3000:3000 \
  -e DRUID_URL=https://your-druid-cluster.com:8888 \
  -e DRUID_USERNAME=your-username \
  -e DRUID_PASSWORD=your-password \
  anilreddy399/apache-druid-mcp:latest --transport sse --port 3000

# Run with stdio transport (for direct MCP communication)
docker run -i \
  -e DRUID_URL=https://your-druid-cluster.com:8888 \
  -e DRUID_USERNAME=your-username \
  -e DRUID_PASSWORD=your-password \
  anilreddy399/apache-druid-mcp:latest

Local Development

npm install
npm run build
npm start

Configuration

Environment Variables

• DRUID_URL - Druid router/broker URL (default: http://localhost:8888)
• DRUID_USERNAME - Authentication username (required for most production clusters)
• DRUID_PASSWORD - Authentication password (required for most production clusters)
• DRUID_TIMEOUT - Request timeout in milliseconds (default: 30000)

Transport Options

# Default stdio transport (for MCP clients)
apache-druid-mcp

# SSE transport for HTTP-based clients
apache-druid-mcp --transport sse --port 3000

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

macOS

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

Windows

%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apache-druid": {
      "command": "npx",
      "args": ["apache-druid-mcp"],
      "env": {
        "DRUID_URL": "https://your-druid-cluster.com:8888",
        "DRUID_USERNAME": "your-username",
        "DRUID_PASSWORD": "your-password"
      }
    }
  }
}

For local development (no authentication):

{
  "mcpServers": {
    "apache-druid": {
      "command": "npx", 
      "args": ["apache-druid-mcp"],
      "env": {
        "DRUID_URL": "http://localhost:8888"
      }
    }
  }
}

VS Code Integration

Using MCP Extension

1. Install the MCP extension for VS Code
2. Add to your VS Code settings.json:

{
  "mcp.servers": {
    "apache-druid": {
      "command": "npx",
      "args": ["apache-druid-mcp"],
      "env": {
        "DRUID_URL": "https://your-druid-cluster.com:8888",
        "DRUID_USERNAME": "your-username",
        "DRUID_PASSWORD": "your-password"
      }
    }
  }
}

Using Codeium or Continue.dev

For HTTP-based AI coding assistants, use SSE transport:

{
  "mcpServers": [
    {
      "name": "apache-druid",
      "url": "http://localhost:3000/sse",
      "env": {
        "DRUID_URL": "https://your-druid-cluster.com:8888",
        "DRUID_USERNAME": "your-username",
        "DRUID_PASSWORD": "your-password"
      }
    }
  ]
}

Start the server with SSE transport:

npx apache-druid-mcp --transport sse --port 3000

Available Tools

The MCP server provides these tools for interacting with Apache Druid:

execute_sql_query

Execute SQL queries against Druid datasources.

Parameters:

• query (string, required) - SQL query to execute
• context (object, optional) - Query context parameters

Example:

SELECT __time, page, COUNT(*) as views 
FROM wikipedia 
WHERE __time >= CURRENT_TIMESTAMP - INTERVAL '1' HOUR 
GROUP BY 1, 2 
ORDER BY views DESC 
LIMIT 10

list_datasources

Get a list of all available datasources in the Druid cluster.

get_datasource_metadata

Get detailed metadata for a specific datasource including schema, segments, size, and intervals.

Parameters:

• datasource (string, required) - Name of the datasource

test_connection

Test connectivity to the Druid cluster and return status information.

Available Resources

Access Druid cluster information through these resources:

• druid://cluster/status - Current cluster status and health
• druid://datasources - List of all datasources
• druid://datasource/{name} - Detailed metadata for specific datasource

Examples

Basic Usage

# Start with default settings
npx apache-druid-mcp

# Connect to remote Druid cluster
DRUID_URL=https://druid.example.com:8888 npx apache-druid-mcp

# With authentication
DRUID_URL=https://secure-druid.com:8888 \
DRUID_USERNAME=admin \
DRUID_PASSWORD=secret \
npx apache-druid-mcp

Using with Claude Desktop

Once configured, you can ask Claude:

• "Show me the available datasources in Druid"
• "Query the wikipedia datasource for top pages in the last hour"
• "What's the schema of the events datasource?"
• "Test the connection to Druid"

Advanced Configuration

# Custom timeout and SSE transport
DRUID_TIMEOUT=60000 npx apache-druid-mcp --transport sse --port 8080

License

Apache License 2.0