com.iunera/druid-mcp-server

Install

Config snippet generator goes here (5 client tabs)

README

# Druid MCP Server
[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/iunera/druid-mcp-server)](https://archestra.ai/mcp-catalog/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](https://www.iunera.com) - 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.

[![Time Series on AI Steroids: Apache Druid Enterprise MCP Server Tutorial](https://img.youtube.com/vi/BqCEWRZbRjU/0.jpg)](https://www.youtube.com/watch?v=BqCEWRZbRjU)

*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](https://github.com/iunera/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.

[![Data Philter](https://raw.githubusercontent.com/iunera/data-philter/main/assets/images/dataphilterinstall.gif)](https://github.com/iunera/data-philter)

[**Get Data Philter on GitHub →**](https://github.com/iunera/data-philter)

## 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](assets/images/mcpinspector-tools.png)

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](assets/images/mcpinspector-resources.png)

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

#### Available Prompts
![MCP Inspector - Prompts](assets/images/mcpinspector-prompts.png)

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)](examples/stdio/README.md) (: see examples/stdio/README.md - server is spawned by the MCP client over STDIO.
* [Streamable HTTP (profile: http)](examples/streamable-http/README.md) : see examples/streamable-http/README.md - single /mcp endpoint per MCP 2025-06-18.


#### Docker examples using environment variables:

```bash
# 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_PROFI