Druid MCP Server

What iunera/druid-mcp-server MCP server does

iunera/druid-mcp-server MCP server exposes Apache Druid operations through the Model Context Protocol. Its interface is divided into three MCP component types: tools for executable operations, resources for retrieving Druid information, and prompts for task-oriented guidance. This makes Druid data and administrative context available to MCP clients without requiring the client to implement Druid API calls directly.

The project is written in Java and integrates with Spring AI's MCP server support. It is intended for environments with an existing Apache Druid cluster, including deployments where a Druid Router is available on port 8888.

How it works

The server connects to Druid using configured service URLs and exposes capabilities according to active Spring profiles. The default configuration uses STDIO transport and enables the query profile. That profile is described as safe and read-only, covering data discovery and querying rather than mutating cluster state.

Transport options include STDIO, SSE, and Streamable HTTP. Streamable HTTP uses an /mcp endpoint when the http profile is enabled. SSE and Streamable HTTP connections use OAuth 2.0 security by default, requiring clients to provide a Bearer token unless OAuth protection is disabled through configuration.

The repository includes an MCP configuration file, Docker examples, and a Ypipe blueprint. The README also describes use with AI clients such as Claude, ChatGPT, and Gemini, but client-specific setup depends on the selected transport and configuration.

Setup and configuration

Running the project requires Java 25. Building from source also requires Maven 3.6 or newer. The application can be packaged with Maven and started from the resulting JAR, or run from the published Docker image. A pre-built JAR is available through Maven Central.

Set DRUID_ROUTER_URL to the Druid Router address and DRUID_COORDINATOR_URL to the Coordinator address when using the documented Docker configuration. The default application port is 8080. To enable HTTP transport, activate the http and query Spring profiles; the documented HTTP configuration exposes /mcp on port 8080.

DRUID_MCP_SECURITY_OAUTH2_ENABLED controls OAuth 2.0 protection. Its documented default is true; setting it to false allows access without OAuth tokens. Enterprise identity-provider integrations such as OpenID Connect, Azure AD, and Keycloak are mentioned as consulting-supported options rather than fully documented local setup paths.

Tools and capabilities

iunera/druid-mcp-server MCP server includes a getDatasources tool for listing Druid datasources or retrieving schema details for a selected datasource. The tool can query table and column metadata and accepts optional datasource and detail parameters.

The getLookups tool retrieves lookup configuration or status for all lookups or a selected tier or lookup name. The getSegments capability provides segment metadata or details. The available tool set is organized around areas such as data management, ingestion management, and monitoring and health, with the exact active set controlled by Spring profiles.

Resources expose accessible Druid datasources and metadata. Prompts provide customizable templates intended to guide data analysis and Druid management tasks. The README presents these components through the MCP Inspector interface.

Limitations and notes

The supplied documentation does not provide a complete inventory of every tool, resource, or prompt; the listed capabilities are examples from the available excerpt. The default query profile is read-only, so write or administrative operations may require another profile and are not guaranteed to be enabled by default.

The server does not include an Apache Druid cluster. A reachable Druid deployment and correctly configured service URLs are required for meaningful use. OAuth behavior differs by transport: STDIO is shown as the default mode, while HTTP and SSE are secured by OAuth 2.0 unless explicitly disabled.