# druid-mcp-server

Connects AI assistants to an Apache Druid cluster to run analytical queries, inspect ingestion tasks, and check coordinator nodes.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 18
- Author: iunera
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/iunera/druid-mcp-server
- Updated: 2026-08-31
- HTML: https://affpapa.org/en/nevibecode/mcp/druid-mcp-server

## What it does

This server bridges LLM agents with Apache Druid using Spring AI. It exposes tools for executing SQL queries against time series data, reading table schemas as resources, and tracking ingestion jobs across cluster services.

Transport works over standard input-output or via Streamable HTTP and SSE endpoints. Network endpoints enforce OAuth 2.0 verification by default; requests will fail without a Bearer token unless `DRUID_MCP_SECURITY_OAUTH2_ENABLED` is turned off. Running outside Docker requires Java 25 alongside Maven 3.6+.

## Requirements
- Needs: Docker
- Environment variables: `DRUID_ROUTER_URL`, `DRUID_COORDINATOR_URL`, `DRUID_AUTH_USERNAME`, `DRUID_AUTH_PASSWORD`, `DRUID_SSL_ENABLED`, `DRUID_SSL_SKIP_VERIFICATION` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env DRUID_ROUTER_URL=<DRUID_ROUTER_URL> --env DRUID_COORDINATOR_URL=<DRUID_COORDINATOR_URL> --env DRUID_AUTH_USERNAME=<DRUID_AUTH_USERNAME> --env DRUID_AUTH_PASSWORD=<DRUID_AUTH_PASSWORD> --env DRUID_SSL_ENABLED=<DRUID_SSL_ENABLED> --transport stdio druid-mcp-server -- docker run -i --rm -e DRUID_ROUTER_URL -e DRUID_COORDINATOR_URL -e DRUID_AUTH_USERNAME -e DRUID_AUTH_PASSWORD -e DRUID_SSL_ENABLED docker.io/iunera/druid-mcp-server:2.0.1
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
codex mcp add druid-mcp-server --env DRUID_ROUTER_URL=<DRUID_ROUTER_URL> --env DRUID_COORDINATOR_URL=<DRUID_COORDINATOR_URL> --env DRUID_AUTH_USERNAME=<DRUID_AUTH_USERNAME> --env DRUID_AUTH_PASSWORD=<DRUID_AUTH_PASSWORD> --env DRUID_SSL_ENABLED=<DRUID_SSL_ENABLED> -- docker run -i --rm -e DRUID_ROUTER_URL -e DRUID_COORDINATOR_URL -e DRUID_AUTH_USERNAME -e DRUID_AUTH_PASSWORD -e DRUID_SSL_ENABLED docker.io/iunera/druid-mcp-server:2.0.1
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "druid-mcp-server": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DRUID_ROUTER_URL",
                "-e",
                "DRUID_COORDINATOR_URL",
                "-e",
                "DRUID_AUTH_USERNAME",
                "-e",
                "DRUID_AUTH_PASSWORD",
                "-e",
                "DRUID_SSL_ENABLED",
                "docker.io/iunera/druid-mcp-server:2.0.1"
            ],
            "env": {
                "DRUID_ROUTER_URL": "<DRUID_ROUTER_URL>",
                "DRUID_COORDINATOR_URL": "<DRUID_COORDINATOR_URL>",
                "DRUID_AUTH_USERNAME": "<DRUID_AUTH_USERNAME>",
                "DRUID_AUTH_PASSWORD": "<DRUID_AUTH_PASSWORD>",
                "DRUID_SSL_ENABLED": "<DRUID_SSL_ENABLED>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "druid-mcp-server": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DRUID_ROUTER_URL",
                "-e",
                "DRUID_COORDINATOR_URL",
                "-e",
                "DRUID_AUTH_USERNAME",
                "-e",
                "DRUID_AUTH_PASSWORD",
                "-e",
                "DRUID_SSL_ENABLED",
                "docker.io/iunera/druid-mcp-server:2.0.1"
            ],
            "env": {
                "DRUID_ROUTER_URL": "<DRUID_ROUTER_URL>",
                "DRUID_COORDINATOR_URL": "<DRUID_COORDINATOR_URL>",
                "DRUID_AUTH_USERNAME": "<DRUID_AUTH_USERNAME>",
                "DRUID_AUTH_PASSWORD": "<DRUID_AUTH_PASSWORD>",
                "DRUID_SSL_ENABLED": "<DRUID_SSL_ENABLED>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e DRUID_ROUTER_URL=<DRUID_ROUTER_URL> -e DRUID_COORDINATOR_URL=<DRUID_COORDINATOR_URL> -e DRUID_AUTH_USERNAME=<DRUID_AUTH_USERNAME> -e DRUID_AUTH_PASSWORD=<DRUID_AUTH_PASSWORD> -e DRUID_SSL_ENABLED=<DRUID_SSL_ENABLED> druid-mcp-server docker run -i --rm -e DRUID_ROUTER_URL -e DRUID_COORDINATOR_URL -e DRUID_AUTH_USERNAME -e DRUID_AUTH_PASSWORD -e DRUID_SSL_ENABLED docker.io/iunera/druid-mcp-server:2.0.1
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- Query Apache Druid datasources using natural language
- Inspect ingestion job progress across cluster coordinators
- Fetch table schemas and metadata into LLM context
- Track cluster health and router availability

## Example prompts
- List all active datasources in my Druid cluster and describe their schema.
- Run an aggregation query on the events table for the past 24 hours.
- Check the execution status of active ingestion tasks on the coordinator.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md