iunera/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 intend-based architecture where profiles picture their usaae intend and the corresponding area of Druid usage. 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*
🌊 Y̊pipe: AI-Powered UI for Druid
Experience your data like never before with **Y̊pipe (formerly Data-Philter)**, a local desktop application that makes offline AI practical, 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 offline models (CPU/GPU).
* **Plug & Play:** Works out-of-the-box with the Development Druid Installation.
**Get Ypipe on GitHub →**
*The easiest way to test iunera/druid-mcp-server is ypipe.com / https://github.com/iunera/ypipe*
📋 Ypipe Integration Blueprint
For seamless integration, we provide a predefined Ypipe integration blueprint file:
* **Blueprint File**: druid.ypipe
* **Configuration Guide**: Ypipe Example Documentation
This blueprint allows you to easily connect and configure the Druid MCP server in Ypipe through a visual workspace.
| Ypipe Workspace Flow | Druid Node Configuration |
| --- | --- |
| | |
Features
- Pure Java
- 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
- **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
The tools interface shows all available Druid management functions organized by feature areas including data management, ingestion management, and monitoring & health.
Available Resources
The resources interface displays all accessible Druid data sources and metadata that can be retrieved through the MCP protocol.
Available 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 multiple integration and 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.
* Ypipe Blueprint: see examples/ypipe/README.md - configure and run the Druid MCP Server inside the Ypipe desktop client using the druid.ypipe blueprint.
Docker examples using environment variables:
Note on Spring profiles:
- Default profile: stdio,query
- HTTP profile: set SPRING_PROFILES_ACTIVE=http,query to enable Streamable HTTP at /mcp
Prerequisites
- Java 25
- Maven 3.6+
- Apache Druid cluster running with router on port 8888
Build and Run
The server will start on port 8080 by default.
For detailed build instructions, testing, Docker setup, and development guidelines, see development.md.
Security & Authentication
- Streamable HTTP and SSE transports are secured with OAuth 2.0 by default.