druid-mcp-server — Claude Code MCP server: what it does
Connects AI assistants to an Apache Druid cluster to run analytical queries, inspect ingestion tasks, and check coordinator nodes.
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.1What druid-mcp-server 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+.
What it helps with
- 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 for the agent
- 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.
How to install druid-mcp-server
Platform CLI
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.1Replace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
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.1Replace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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.1Replace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about druid-mcp-server
How do I install druid-mcp-server in Claude Code?
Run this command in your terminal: `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 placeholders with your Druid router and coordinator endpoints.
What does druid-mcp-server do?
It exposes Druid query endpoints, metadata resources, and health checks as MCP primitives so coding assistants can interact directly with your analytics cluster.
What are the prerequisites to run this MCP server?
You need an active Apache Druid cluster with reachable router and coordinator services. Running the application directly requires Java 25 and Maven 3.6+, while containerized deployments require Docker.
