Iunera Druid MCP Server

Manage and analyze Apache Druid clusters through natural language with tools for datasource management, ingestion, retention, compaction, and cluster health monitoring. Built for developers integrating AI agents with Druid via MCP protocol.

com.iunera/druid-mcp-server

Environment variables

Configuration this server reads at startup.

DRUID_ROUTER_URLRequired

Druid router URL for connecting to the Druid cluster

DRUID_COORDINATOR_URL

Druid coordinator URL for querying metadata endpoints (optional)

DRUID_AUTH_USERNAME

Username for Druid authentication (optional)

DRUID_AUTH_PASSWORDSecret

Password for Druid authentication (optional)

DRUID_SSL_ENABLED

Enable SSL/TLS support for Druid connections

DRUID_SSL_SKIP_VERIFICATION

Skip SSL certificate verification (for development/testing only)

DRUID_MCP_READONLY_ENABLED

Enable read-only mode (only GET requests and SQL queries allowed)

Example prompts for Iunera Druid

Paste any of these into Agent Studio after connecting Iunera Druid.

List all datasources and show details for the largest one by segment count

Execute a SQL query to find top 10 events by timestamp from my main datasource

Check cluster health status and run diagnostics if any services are down

View retention rules for all datasources and update the rule for datasource_prod

Excerpted from the project's README — boilerplate sections (license, changelog, contributing) omitted for clarity.

Druid MCP Server

A comprehensive Model Context Protocol (MCP) server for Apache Druid that provides extensive tools, resources, and prompts for managing and analyzing Druid clusters.

Developed by iunera - Advanced AI and Data Analytics Solutions

Overview

This MCP server implements a feature-based architecture where each package represents a distinct functional area of Druid management. The server provides three main types of MCP components:

Tools - Executable functions for performing operations
Resources - Data providers for accessing information
Prompts - AI-assisted guidance templates

Video Walkthrough

Learn how to integrate AI agents with Apache Druid using the MCP server. This tutorial demonstrates time series data exploration, statistical analysis, and data ingestion using natural language with AI assistants like Claude, ChatGPT, and Gemini.

Click the thumbnail above to watch the video on YouTube

🧠 Data Philter: AI-Powered UI for Druid

Experience your data like never before with Data Philter, a local-first AI gateway designed by iunera. It leverages this Druid MCP Server to provide a seamless, conversational interface for your Druid cluster.

Natural Language Queries: Ask questions in plain English and get results instantly.
Local & Secure: Runs completely locally with support for Ollama models (or OpenAI).
Plug & Play: Works out-of-the-box with the Development Druid Installation.

Get Data Philter on GitHub →

Features

Spring AI MCP Server integration
Tool-based architecture for MCP protocol compliance
Tool-based Architecture: Complete MCP protocol compliance with automatic JSON schema generation
Multiple Transport Modes: STDIO, SSE, and Streamable HTTP support including Oauth
Real-time Communication: Server-Sent Events with streaming capabilities
Comprehensive error handling
Customizable Prompt Templates: AI-assisted guidance with template customization
Comprehensive Error Handling: Graceful error handling with meaningful responses

Architecture & Organization

Feature-based Package Organization: Each package represents a distinct Druid management area
Auto-discovery: Automatic registration of tools, resources, and prompts via annotations
Enterprise Ready: Production-grade configuration and security features

MCP Inspector Interface

When connected to an MCP client, you can inspect the available tools, resources, and prompts through the MCP inspector interface:

Available Tools

MCP Inspector - Tools

The tools interface shows all available Druid management functions organized by feature areas including data management, ingestion management, and monitoring & health.

Available Resources

MCP Inspector - Resources

The resources interface displays all accessible Druid data sources and metadata that can be retrieved through the MCP protocol.

Available Prompts

MCP Inspector - Prompts

The prompts interface shows all AI-assisted guidance templates available for various Druid management tasks and data analysis workflows.

Quick Start

MCP Configuration for LLMs

A ready-to-use MCP configuration file is provided at mcp-servers-config.json that can be used with LLM clients to connect to this Druid MCP server.

Examples

The configuration includes both transport options:

STDIO default) (: see examples/stdio/README.md - server is spawned by the MCP client over STDIO.
Streamable HTTP (profile: http) : see examples/streamable-http/README.md - single /mcp endpoint per MCP 2025-06-18.

Docker examples using environment variables:

# STDIO mode (default)
docker run --rm -i \
  -e DRUID_ROUTER_URL=http://your-druid-router:8888 \
  -e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
  iunera/druid-mcp-server:latest

# HTTP mode (enable profile 'http' and expose /mcp)
docker run -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=http \
  -e DRUID_ROUTER_URL=http://your-druid-router:8888 \
  -e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \
  iunera/druid-mcp-server:latest

Note on Spring profiles:

Default profile: stdio (no SPRING_PROFILES_ACTIVE needed)
HTTP profile: set SPRING_PROFILES_ACTIVE=http to enable Streamable HTTP at /mcp

Prerequisites

Java 25
Maven 3.6+
Apache Druid cluster running with router on port 8888

Build and Run

# Build the application
mvn clean package -DskipTests

# Run the application
java -jar target/druid-mcp-server-1.8.2.jar

The server will start on port 8080 by default.

For detailed build instructions, testing, Docker setup, and development guidelines, see development.md.

Iunera Druid MCP server — FAQ

Common questions about connecting and running Iunera Druid.

What Druid operations can this MCP server perform?

It provides tools for datasource management (list, kill, show details), segment inspection, SQL queries, retention and compaction rule management, ingestion task/supervisor control, and cluster health diagnostics. Read-only mode restricts operations to GET requests and SQL queries only.

How do I authenticate the server to my Druid cluster?

Set DRUID_ROUTER_URL (required) and optionally DRUID_COORDINATOR_URL, DRUID_AUTH_USERNAME, and DRUID_AUTH_PASSWORD as environment variables. For HTTP transport, OAuth2 is enabled by default; disable it by setting DRUID_MCP_SECURITY_OAUTH2_ENABLED=false.

Can I run this in read-only mode?

Yes, set DRUID_MCP_READONLY_ENABLED=true to allow only GET requests and SQL queries. Modification tools like killDatasource and updateRetentionRules will not be registered in read-only mode.

What transport modes does this server support?

It supports STDIO (default), Server-Sent Events (SSE), and Streamable HTTP. Use SPRING_PROFILES_ACTIVE=http to enable HTTP mode on port 8080, or leave it unset for STDIO mode.

Is SSL/TLS supported for Druid connections?

Yes, enable it with DRUID_SSL_ENABLED=true. For development/testing, you can skip certificate verification with DRUID_SSL_SKIP_VERIFICATION=true, though this is not recommended for production.