Druid MCP Server

Community

A comprehensive MCP server for Apache Druid cluster management and analytics

★ 18 Stars Category · Database Popular Source revision 08cbd4deb172

55FMRS · C

This is a well-crafted MCP server by iunera, a veteran in Apache Druid, to bridge AI assistants with Druid clusters. It stands out for its extensive tool set, feature-wise Spring profiles, and enterprise-grade features like the Streamable HTTP transport. Security is a key aspect, with OAuth2 by default. Its operational requirements are relatively demanding (Java 25, sometimes Docker) and require a user familiar with connecting to Druid clusters to manage it reliably. While it is a huge asset for production Druid users, its complexity may deter beginners.

Reliability

10/20

Security and permissions

8/20

Maintenance

12/20

Documentation

13/20

Setup experience

12/20

Read the FMRS scoring method →

Druid MCP Server is iunera's comprehensive Model Context Protocol (MCP) server for Apache Druid. It is built with Spring Boot and Spring AI and integrates AI assistants with Druid clusters seamlessly. The server provides tools, resources, and prompts to support both the management and analysis of Druid clusters. Its capabilities range from basic data querying and browsing (e.g., listing datasources, segments, executing SQL) to more advanced operations such as ingestion management, supervisor monitoring, retention rules, compaction, multi-stage queries, and security/authorization administration. It supports multiple transport modes (STDIO, SSE, and streamable HTTP) and is tunable via Spring profiles, enabling controlled production use.

Tools

getDatasources

List all available Apache Druid datasources or get detailed schema for a specific datasource.

getLookups

Get configuration or status of lookups for all or a specific tier.

getSegments

Fetch segment metadata or details for a specific segment.

getSegmentLoadQueue

Get the load queue status showing segments currently being loaded.

queryDruidSql

Execute a SQL query against Druid datasources.

getCompactionConfig

View compaction configuration or configuration change history for datasources.

getCompactionStatus

Retrieve the current status of compaction runs and progress.

manageCompaction

Add, update, or remove a compaction configuration.

manageDatasourceOrSegment

Modify segment states or permanently drop a datasource.

manageLookup

Create, update, or delete a lookup configuration.

queryDruidMultiStage

Execute a multi-stage SQL (MSQ) query against Druid datasources as a task.

queryDruidMultiStageWithContext

Execute a multi-stage SQL query with custom context parameters.

getMultiStageQueryTaskStatus

Get the status of a multi-stage query task.

cancelMultiStageQueryTask

Cancel a running multi-stage query task.

getRetentionRules

Retrieve retention rules or audit history for a specific datasource or all datasources.

manageRetentionRules

Update retention rules configuration for a specific datasource.

submitIngestion

Submit a Druid ingestion specification or generate a simple batch template.

getSupervisors

List all supervisors or query details of a specific supervisor.

manageSupervisor

Suspend, resume, or terminate a supervisor's execution.

getTasks

List ingestion tasks matching specific states.

getTaskDetails

Fetch detailed information, specifications, execution reports, or execution logs for a task.

shutdownTask

Kill/shutdown a Druid task.

getClusterStatus

Check overall health or fetch specific metadata/properties from coordinators or routers.

getNodesStatus

List registered servers, their detailed status, or single node status.

diagnoseCluster

Perform automated diagnostic health checks, configuration audits, or query performance analysis.

checkFunctionalityHealth

Validate the operation of ingestion systems, supervisor state transitions, and historical query latency.

manageAuthentication

Administer basic security users and credentials.

manageAuthorization

Manage security authorization properties, roles, and resource access policies.

manageSecurityAssignments

Configure mapping rules assigning roles to users, or retrieve the configured authenticator chains.

Setup

Ensure you have Java 25 runtime or Docker available.
Have a reachable Apache Druid cluster, with its Router URL (default port 8888) and optionally Coordinator URL (port 8081).
If using Docker, run 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.
For Streamable HTTP mode, run with the http profile active, e.g., set SPRING_PROFILES_ACTIVE=http,query to expose an endpoint at http://localhost:8080/mcp.
Configure your MCP client with the JSON config example above, setting the necessary environment variables.

claude_desktop_config.json

{
  "mcpServers": {
    "druid-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DRUID_ROUTER_URL",
        "-e",
        "DRUID_COORDINATOR_URL",
        "-e",
        "DRUID_AUTH_USERNAME",
        "-e",
        "DRUID_AUTH_PASSWORD",
        "-e",
        "DRUID_SSL_ENABLED",
        "-e",
        "DRUID_SSL_SKIP_VERIFICATION",
        "iunera/druid-mcp-server:latest"
      ],
      "env": {
        "DRUID_ROUTER_URL": "http://host.docker.internal:8888",
        "DRUID_COORDINATOR_URL": "http://host.docker.internal:8081",
        "DRUID_AUTH_USERNAME": "",
        "DRUID_AUTH_PASSWORD": "",
        "DRUID_SSL_ENABLED": "false",
        "DRUID_SSL_SKIP_VERIFICATION": "true"
      }
    }
  }
}

Generate and validate client config

Fit and risk

Best for

Data analysts and engineers who want to query and explore Apache Druid data via AI assistants like Claude, ChatGPT, or Gemini using natural language.
Teams looking to automate or streamline Druid cluster management tasks such as monitoring tasks, compaction, retention rules, and ingestion.
Developers integrating MCP clients via supported transports (STDIO, Streamable HTTP) looking for a standard 'out-of-the-box' server to interact with Druid.
Users who want a conversational data interface in a local desktop application such as Ypipe.

Not for

Not for latency-sensitive real-time data operations when MCP session overhead is unacceptable.
Not for headless, non-interactive scenarios where MCP protocol abstraction is unnecessary.
Not for users who require deep, custom Druid API capabilities or complex workflows that are not exposed through the MCP.
Not for those looking for a server to interoperate with cloud-hosted services such as Imply Polaris.

Required permissions

Must be provided with URLs for Druid Router (required) and Coordinator (recommended) via environment variables.
Optionally provide Druid username and password for authentication via HTTP Basic.
For HTTP transports, OAuth2 is enabled by default and requires clients to present a valid Bearer token.
Varying permissions are required for admin operations depending on which Spring profiles are active (`ops`, `permissions`, `health`).
Read access to Druid system tables/catalog and data access depending on the scope of queries.

Risks and side effects

Risk of unintentional data deletion or modification when the `ops` profile is active and tokens are compromised, as `manageDatasourceOrSegment` allows permanently dropping datasources.
Using SSL with disabled certificate verification (`DRUID_SSL_SKIP_VERIFICATION=true`) can expose connections to man-in-the-middle attacks.
Exposing sensitive cluster metadata and query results to AI assistants may lead to data leakage.
The `permissions` tools can modify users, roles, and authorization policies when proper permissions are held.
Because tools are activated on-demand based on Spring profiles, there is a risk of misconfiguration if the required profiles are not activated correctly.

Troubleshooting

Check environment variables: confirm `DRUID_ROUTER_URL` is set with the correct protocol (http/https) and port.
Verify the Druid cluster is running and the router endpoint is reachable from the MCP server's environment.
For HTTP mode, ensure the `http` Spring profile is active (`SPRING_PROFILES_ACTIVE=http,...`), otherwise the server might be in STDIO mode and not listening on any port.
For HTTP mode with authentication, ensure your MCP client is configured with a valid OAuth2 token or disable via `DRUID_MCP_SECURITY_OAUTH2_ENABLED=false` (for testing).
If you don't see the expected tools, check the enabled Spring profiles; for example, `getTasks` is available under `ops`, while only safe read-only tools are provided under `query`.

Use cases

Time series data exploration in Apache Druid using natural language

Managing and monitoring Druid cluster tasks, supervisors, and compaction via AI assistants

SQL query optimization and performance analysis with AI assistants

Controlled data ingestion management through AI assistants

Seamless conversational data interfaces in local desktop apps like Ypipe

Supported clients

Claude DesktopFull support

Generic MCP ClientFull support

Related MCP servers

Compare with other MCP servers