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 byiunera- Advanced AI and Data Analytics Solutions

Experience your data like never before withY̊pipe (formerly Data-Philter), a local desktop application that makes offline AI practical, designed by iunera. It leverages thisDruid MCP Serverto provide a seamless, conversational interface for your Druid cluster.

The easiest way to test iunera/druid-mcp-server isypipe.com/https://github.com/iunera/ypipe

- Blueprint File:druid.ypipe
- Configuration Guide:Ypipe Example Documentation

This blueprint allows you to easily connect and configure the Druid MCP server inYpipethrough a visual workspace.

- STDIO (default): see examples/stdio/README.md - server is spawned by the MCP client over STDIO.
- Streamable HTTP (profile: http): see examples/streamable-http/README.md - single /mcp endpoint per MCP 2025-06-18.
- Ypipe Blueprint: see examples/ypipe/README.md - configure and run the Druid MCP Server inside theYpipedesktop client using thedruid.ypipeblueprint.

# 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,query \ -e DRUID_ROUTER_URL=http://your-druid-router:8888 \ -e DRUID_COORDINATOR_URL=http://your-druid-coordinator:8081 \ iunera/druid-mcp-server:latest

# Build the application mvn clean package -DskipTests # Run the application java -jar target/druid-mcp-server-2.0.0.jar

For detailed build instructions, testing, Docker setup, and development guidelines, seedevelopment.md.

- For enterprise SSO integration (OpenID Connect, Azure AD, Keycloak, etc.), please send an inquiry toconsulting@iunera.comand seeContact & Support.

Download the JAR from Maven Centralhttps://repo.maven.apache.org/maven2/com/iunera/druid-mcp-server/

# STDIO mode (default) java -jar target/druid-mcp-server-2.0.0.jar # HTTP mode (profile: http) - exposes /mcp on port 8080 java -Dspring.profiles.active=http \ -jar target/druid-mcp-server-2.0.0.jar

For detailed development information including build instructions, testing guidelines, architecture details, and contributing guidelines, seedevelopment.md.

[!IMPORTANT] Basic security tools are only activated ifbothof the following conditions are met:
- Thepermissionsprofile is activated (spring.profiles.active=permissions).
- The Coordinator URL (druid.coordinator.url) is set and non-empty.

Provides active health checking, cluster status, diagnostics, and doctor recommendation scans.

The application can be configured using environment variables, which is the recommended approach for production environments. Below is a comprehensive list of supported environment variables derived from theapplication.yamlconfiguration file.

- DRUID_ROUTER_URL: The URL of the Druid router.
- DRUID_AUTH_USERNAME: The username for Druid authentication.
- DRUID_AUTH_PASSWORD: The password for Druid authentication.
- DRUID_SSL_ENABLED: Enables or disables SSL for Druid connections (true/false).
- DRUID_SSL_SKIP_VERIFICATION: Skips SSL certificate verification (true/false).
- DRUID_MCP_SQL_SYNTAX_CORRECTION_ENABLED: Enables or disables automatic SQL syntax correction (default:true). When enabled, automatically formats queries, corrects casing, and quotes identifiers for Druid.
- DRUID_MCP_SQL_SYNTAX_CORRECTION_CACHE_TTL_MS: The Time-To-Live (TTL) in milliseconds for the cached table and column metadata loaded from Druid (default:300000/ 5 minutes).

- DRUID_MCP_SECURITY_OAUTH2_ENABLED: Enables or disables OAuth2 security for HTTP client authentication (true/false).
- SPRING_PROFILES_ACTIVE: Comma-separated list of profiles to activate (e.g.query,ops,permissions,healthfor tools capabilities, orhttpto enable HTTP server transport instead of default STDIO).
- SPRING_AI_MCP_SERVER_NAME: The name of the MCP server.
- SPRING_AI_MCP_SERVER_PROTOCOL: The protocol used by the MCP server (e.g.,streamable).

- LOGGING_FILE_NAME: The name of the log file.
- LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY: The log level for Spring Security (e.g.,DEBUG).

SSL-Encrypted Cluster with Authentication

This section provides comprehensive guidance on connecting to SSL-encrypted Druid clusters with username and password authentication.

- SSL-enabled Druid cluster with HTTPS endpoints
- Valid username and password credentials for Druid authentication
- SSL certificates properly configured (or ability to skip verification for testing)

Set the following environment variables before starting the MCP server:

# Druid cluster URL with HTTPS export DRUID_ROUTER_URL="https://your-druid-cluster.example.com:8888" # Authentication credentials export DRUID_AUTH_USERNAME="your-username" export DRUID_AUTH_PASSWORD="your-password" # SSL configuration export DRUID_SSL_ENABLED="true" export DRUID_SSL_SKIP_VERIFICATION="false" # Use "true" only for testing # Start the MCP server java -jar target/druid-mcp-server-2.0.0.jar

Pass configuration as JVM system properties:

java -Ddruid.router.url="http://localhost:8888" \ -Ddruid.auth.username="admin" \ -Ddruid.auth.password="password" \ -jar target/druid-mcp-server-2.0.0.jar

For production environments with valid SSL certificates:

export DRUID_ROUTER_URL="https://druid-prod.company.com:8888" export DRUID_SSL_ENABLED="true" export DRUID_SSL_SKIP_VERIFICATION="false"

The server will use the system's default truststore to validate SSL certificates.

The MCP server supports HTTP Basic Authentication with username and password:

- Username: Set viaDRUID_AUTH_USERNAMEordruid.auth.username
- Password: Set viaDRUID_AUTH_PASSWORDordruid.auth.password

The credentials are automatically encoded using Base64 and sent with each request using theAuthorization: Basicheader.

Update yourmcp-servers-config.jsonto include environment variables:

{ "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:2.0.0" ], "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" } } } }

The server provides extensive prompt customization capabilities through theprompts.propertiesfile located insrc/main/resources/.
- Global Settings: Enable/disable prompts and set watermarks
- Feature Toggles: Control which prompts are available
- Custom Variables: Organization-specific information
- Template Definitions: Full prompt templates for each feature

You can override any prompt template using Java system properties with the-Dflag:

Method 1: System Properties (Runtime Override)

java -Dprompts.druid-data-exploration.template="Your custom template here" \ -jar target/druid-mcp-server-2.0.0.jar

- Create a custom properties file (e.g.,custom-prompts.properties):

# Custom prompt template prompts.druid-data-exploration.template=My custom data exploration prompt:\n\ 1. Custom step one\n\ 2. Custom step two\n\ {datasource_section}\n\ Environment: {environment}

java -Dspring.config.additional-location=classpath:custom-prompts.properties \ -jar target/druid-mcp-server-2.0.0.jar

All prompt templates support these variables:

prompts.druid-data-exploration.template=Welcome to {organizationName} Druid Analysis!\n\n\ Please help me explore our data:\n\ {datasource_section}\n\ Environment: {environment}\n\ Contact: {contactInfo}\n\n\ {watermark}

prompts.druid-query-optimization.template=Query Performance Analysis for {organizationName}\n\n\ Query to optimize: {query}\n\n\ Please provide:\n\ 1. Performance bottleneck analysis\n\ 2. Optimization recommendations\n\ 3. Best practices for our {environment} environment\n\n\ {watermark}

You can disable individual prompts by setting their enabled flag to false:

mcp.prompts.data-exploration.enabled=false mcp.prompts.query-optimization.enabled=false

This server uses Spring AI's MCP Server framework and supports both STDIO and SSE transports. The tools, resources, and prompts are automatically registered and exposed through the MCP protocol.

The Druid MCP Server supports multiple transport modes compliant with MCP 2025-06-18 specification:

The newStreamable HTTPtransport provides enhanced performance and scalability with support for multiple concurrent clients:

# Default configuration with Streamable HTTP java -Dspring.profiles.active=http \ -jar target/druid-mcp-server-2.0.0.jar # Server available at http://localhost:8080/mcp (configurable endpoint)

- Single Endpoint: One HTTP endpoint handles both POST and GET requests
- Multiple Clients: Support for concurrent client connections
- Optional SSE Streaming: Server-Sent Events for real-time updates
- Enhanced Security: Origin header validation and authentication
- Backwards Compatibility: Automatic fallback for older MCP clients
- Keep-alive: Configurable connection health monitoring

- The Streamable HTTP and SSE modes are secured with OAuth by default. Your MCP client must obtain and send a valid bearer token when connecting.
- For enterprise SSO integration (OpenID Connect, Azure AD, Keycloak, etc.), please send an inquiry toconsulting@iunera.comand seeContact & Support.