Apache Druid MCP Server for Management and Analysis

Overview

The Apache Druid MCP Server (Model Context Protocol server) is an adapter layer designed to simplify management, monitoring, and analysis of Apache Druid clusters. It exposes a consistent API and a collection of developer-facing tools and prompts that help operators inspect cluster state, run diagnostics, tune queries, and automate routine operational tasks.

Built as an extensible middleware service, the MCP server centralizes cluster information and translates it into actionable outputs—including dashboards, standardized endpoints, and AI-style prompts for common workflows. It’s useful for teams that want a programmable interface on top of Druid for operational automation, faster troubleshooting, and repeatable analysis.

Repository and source code are available at: https://github.com/iunera/druid-mcp-server

Features

• Centralized API for Druid cluster metadata, tasks, segments, and nodes
• Predefined tools for monitoring, query analysis, and segment management
• Prompts and templates for generating diagnostics and remediation steps
• Lightweight web server and REST endpoints for integration with CI/CD or alerting
• Docker and source build options for flexible deployment
• Extensible plugin points to add custom tools or integrate with other observability systems

Installation / Configuration

Prerequisites: Java 11+ (or OpenJDK 17+ recommended), Maven (if building from source), Docker (optional)

Clone and build from source:

git clone https://github.com/iunera/druid-mcp-server.git
cd druid-mcp-server
mvn clean package -DskipTests
java -jar target/druid-mcp-server.jar

Run with Docker (example docker-compose):

version: '3.7'
services:
  druid-mcp-server:
    image: iunera/druid-mcp-server:latest
    ports:
      - "8080:8080"
    environment:
      DRUID_COORDINATOR_URL: "http://druid-coordinator:8081"
      DRUID_OVERLORD_URL: "http://druid-overlord:8090"
      SERVER_PORT: "8080"

Environment variables (common):

# Core Druid endpoints
DRUID_COORDINATOR_URL=http://localhost:8081
DRUID_OVERLORD_URL=http://localhost:8090
DRUID_BROKER_URL=http://localhost:8082

# Server
SERVER_PORT=8080
LOG_LEVEL=INFO

# Optional authentication
API_KEY=your_secret_key

Configuration file example (config.yaml):

server:
  port: 8080

druid:
  coordinatorUrl: "http://localhost:8081"
  overlordUrl: "http://localhost:8090"
  brokerUrl: "http://localhost:8082"

security:
  apiKey: "change-me"

Quick start test (health endpoint):

curl -H "Authorization: Bearer ${API_KEY}" http://localhost:8080/health

Available Tools / Resources

The MCP server packages several developer-facing tools and resources that you can use immediately:

• Cluster Overview: consolidated metadata about nodes, segments, and data sources
• Tasks / Ingestion Manager: list and status of ingestion tasks, with retry recommendations
• Segment Explorer: segment distribution, replication state, and compaction suggestions
• SQL Console: execute Druid SQL queries via the MCP proxy with result preview
• Metrics Explorer: time-series charts for query latency, CPU, and JVM metrics (exportable CSV)
• Alerts & Diagnostics: rules for detecting slow queries, task failures, and under-replicated segments
• Prompts Library: templated prompts to generate analysis steps and remediation commands (designed to be used with LLM tooling or automation scripts)

Example API endpoints:

Use Cases

1. Troubleshoot a slow analytic query

   • Use the SQL Console to reproduce the query.
   • Fetch query plan and runtime metrics via /api/cluster and /api/metrics.
   • Use the Prompts Library to generate tuning suggestions (e.g., segment granularity, indexes to add).

2. Detect and resolve under-replicated segments

   • Periodically query /api/segments to find segments with replica counts below threshold.
   • Trigger a compaction or rebalancing workflow via the Tasks tool and monitor progress.

3. Automate ingestion task recovery

   • Watch /api/tasks for FAILED status.
   • Use the diagnostics endpoint to capture failure logs and recommended retries.
   • Execute a scripted retry or roll-forward using the Overlord API through the MCP proxy.

4. Capacity planning and historical analysis

   • Export metrics from the Metrics Explorer for CPU, query load, and segment growth.
   • Run trend analysis to forecast storage and compute needs for the next quarter.

5. Integrate with CI/CD or alerting

   • Call /api/diagnose from an alerting webhook to attach automated diagnostic reports when a cluster alert fires.
   • Incorporate SQL schema checks as part of a data pipeline deployment.

Getting Help and Extending

• Source and issues: https://github.com/iunera/druid-mcp-server
• To add custom tools, implement the extension interface in the server codebase and register new endpoints.
• For production, secure the server behind a reverse proxy and enable API keys or OAuth for access control.

This MCP server is intended as a developer-friendly bridge between operations teams and Apache Druid internals. It groups common operational tasks into reusable tools and automations so teams can monitor, analyze, and manage Druid clusters more efficiently.