Provides comprehensive tools for managing and analyzing Apache Druid clusters, including data management, ingestion management, monitoring, and health checks. Enables executing SQL queries, managing datasources, compaction, retention rules, segments, and streaming ingestion supervisors.
Supports deployment via Docker with pre-built images available on Docker Hub, offering configuration through environment variables for connecting to Druid clusters with options for both SSE and STDIO transport modes.
Planned future integration for deploying the Druid MCP Server on Kubernetes clusters, mentioned in the roadmap section.
Integrates with PostgreSQL as the metadata storage for Apache Druid clusters, supporting the backend infrastructure for the Druid management capabilities.
A comprehensive Model Context Protocol (MCP) server for Apache Druid that provides extensive tools, resources, and prompts for managing and analyzing Druid clusters.
Developed by iunera - Advanced AI and Data Analytics Solutions
This MCP server implements a feature-based architecture where each package represents a distinct functional area of Druid management. The server provides three main types of MCP components:
Learn how to integrate AI agents with Apache Druid using the MCP server. This tutorial demonstrates time series data exploration, statistical analysis, and data ingestion using natural language with AI assistants like Claude, ChatGPT, and Gemini.
Click the thumbnail above to watch the video on YouTube
When connected to an MCP client, you can inspect the available tools, resources, and prompts through the MCP inspector interface:
The tools interface shows all available Druid management functions organized by feature areas including data management, ingestion management, and monitoring & health.
The resources interface displays all accessible Druid data sources and metadata that can be retrieved through the MCP protocol.
The prompts interface shows all AI-assisted guidance templates available for various Druid management tasks and data analysis workflows.
The server will start on port 8080 by default.
For detailed build instructions, testing, Docker setup, and development guidelines, see development.md.
If you prefer to use the pre-built JAR without building from source, you can download and run it directly from Maven Central.
If you prefer to use Docker, you can run the pre-built Docker image directly from Docker Hub without any local Java installation.
Replace your-druid-broker and your-druid-coordinator with your actual Druid cluster endpoints.
For detailed development information including build instructions, testing guidelines, architecture details, and contributing guidelines, see development.md.
| Feature | Tool | Description | Parameters |
|---|---|---|---|
| Datasource | listDatasources | List all available Druid datasource names | None |
| Datasource | showDatasourceDetails | Show detailed information for a specific datasource including column information | datasourceName (String) |
| Datasource | killDatasource | Kill a datasource permanently, removing all data and metadata | datasourceName (String), interval (String) |
| Lookup | listLookups | List all available Druid lookups from the coordinator | None |
| Lookup | getLookupConfig | Get configuration for a specific lookup | tier (String), lookupName (String) |
| Lookup | updateLookupConfig | Update configuration for a specific lookup | tier (String), lookupName (String), config (String) |
| Segments | listAllSegments | List all segments across all datasources | None |
| Segments | getSegmentMetadata | Get metadata for specific segments | datasourceName (String), segmentId (String) |
| Segments | getSegmentsForDatasource | Get all segments for a specific datasource | datasourceName (String) |
| Query | queryDruidSql | Execute a SQL query against Druid datasources | sqlQuery (String) |
| Retention | viewRetentionRules | View retention rules for all datasources or a specific one | datasourceName (String, optional) |
| Retention | updateRetentionRules | Update retention rules for a datasource | datasourceName (String), rules (String) |
| Compaction | viewAllCompactionConfigs | View compaction configurations for all datasources | None |
| Compaction | viewCompactionConfigForDatasource | View compaction configuration for a specific datasource | datasourceName (String) |
| Compaction | editCompactionConfigForDatasource | Edit compaction configuration for a datasource | datasourceName (String), config (String) |
| Compaction | deleteCompactionConfigForDatasource | Delete compaction configuration for a datasource | datasourceName (String) |
| Compaction | viewCompactionStatus | View compaction status for all datasources | None |
| Compaction | viewCompactionStatusForDatasource | View compaction status for a specific datasource | datasourceName (String) |
| Feature | Tool | Description | Parameters |
|---|---|---|---|
| Ingestion Spec | createBatchIngestionTemplate | Create a batch ingestion template | datasourceName (String), inputSource (String), timestampColumn (String) |
| Ingestion Spec | createIngestionSpec | Create and submit an ingestion specification | specJson (String) |
| Supervisors | listSupervisors | List all streaming ingestion supervisors | None |
| Supervisors | getSupervisorStatus | Get status of a specific supervisor | supervisorId (String) |
| Supervisors | suspendSupervisor | Suspend a streaming supervisor | supervisorId (String) |
| Supervisors | startSupervisor | Start or resume a streaming supervisor | supervisorId (String) |
| Supervisors | terminateSupervisor | Terminate a streaming supervisor | supervisorId (String) |
| Tasks | listTasks | List all ingestion tasks | None |
| Tasks | getTaskStatus | Get status of a specific task | taskId (String) |
| Tasks | shutdownTask | Shutdown a running task | taskId (String) |
| Feature | Tool | Description | Parameters |
|---|---|---|---|
| Basic Health | checkClusterHealth | Check overall cluster health status | None |
| Basic Health | getServiceStatus | Get status of specific Druid services | serviceType (String) |
| Basic Health | getClusterConfiguration | Get cluster configuration information | None |
| Diagnostics | runDruidDoctor | Run comprehensive cluster diagnostics | None |
| Diagnostics | analyzePerformanceIssues | Analyze cluster performance issues | None |
| Diagnostics | generateHealthReport | Generate detailed health report | None |
| Functionality | testQueryFunctionality | Test query functionality across services | None |
| Functionality | testIngestionFunctionality | Test ingestion functionality | None |
| Functionality | validateClusterConnectivity | Validate connectivity between cluster components | None |
| Feature | Resource URI Pattern | Description | Parameters |
|---|---|---|---|
| Datasource | druid://datasource/{datasourceName} | Access datasource information and metadata | datasourceName (String) |
| Datasource | druid://datasource/{datasourceName}/details | Access detailed datasource information including schema | datasourceName (String) |
| Lookup | druid://lookup/{tier}/{lookupName} | Access lookup configuration and data | tier (String), lookupName (String) |
| Segments | druid://segment/{segmentId} | Access segment metadata and information | segmentId (String) |
| Feature | Prompt Name | Description | Parameters |
|---|---|---|---|
| Data Analysis | data-exploration | Guide for exploring data in Druid datasources | datasource (String, optional) |
| Data Analysis | query-optimization | Help optimize Druid SQL queries for better performance | query (String) |
| Cluster Management | health-check | Comprehensive cluster health assessment guidance | None |
| Cluster Management | cluster-overview | Overview and analysis of cluster status | None |
| Ingestion Management | ingestion-troubleshooting | Troubleshoot ingestion issues | issue (String, optional) |
| Ingestion Management | ingestion-setup | Guide for setting up new ingestion pipelines | dataSource (String, optional) |
| Retention Management | retention-management | Manage data retention policies | datasource (String, optional) |
| Compaction | compaction-suggestions | Optimize segment compaction configuration | datasource (String, optional), currentConfig (String, optional), performanceMetrics (String, optional) |
| Compaction | compaction-troubleshooting | Troubleshoot compaction issues | issue (String), datasource (String, optional) |
| Operations | emergency-response | Emergency response procedures and guidance | None |
| Operations | maintenance-mode | Cluster maintenance procedures | None |
Configure your Druid connection in src/main/resources/application.properties:
For sensitive credentials like username and password, you can use environment variables instead of hardcoding them in properties files.
DRUID_AUTH_USERNAME: Druid authentication usernameDRUID_AUTH_PASSWORD: Druid authentication password DRUID_ROUTER_URL: Override the default Druid router URLDRUID_SSL_ENABLED: Enable SSL/TLS support (true/false)DRUID_SSL_SKIP_VERIFICATION: Skip SSL certificate verification (true/false)This section provides comprehensive guidance on connecting to SSL-encrypted Druid clusters with username and password authentication.
Set the following environment variables before starting the MCP server:
Update src/main/resources/application.properties:
Pass configuration as JVM system properties:
For production environments with valid SSL certificates:
The server will use the system's default truststore to validate SSL certificates.
For development or testing with self-signed certificates:
⚠️ Security Warning: Never use DRUID_SSL_SKIP_VERIFICATION=true in production environments as it disables SSL certificate validation.
The MCP server supports HTTP Basic Authentication with username and password:
DRUID_AUTH_USERNAME or druid.auth.usernameDRUID_AUTH_PASSWORD or druid.auth.passwordThe credentials are automatically encoded using Base64 and sent with each request using the Authorization: Basic header.
Update your mcp-servers-config.json to include environment variables:
The server provides extensive prompt customization capabilities through the prompts.properties file located in src/main/resources/.
The prompts.properties file contains:
You can override any prompt template using Java system properties with the -D flag:
custom-prompts.properties):All prompt templates support these variables:
| Variable | Description | Example |
|---|---|---|
{environment} | Current environment name | production, staging, dev |
{organizationName} | Organization name | Your Organization |
{contactInfo} | Contact information | your-team@company.com |
{watermark} | Generated watermark | Generated by Druid MCP Server v1.0.0 |
{datasource} | Datasource name (context-specific) | sales_data |
{query} | SQL query (context-specific) | SELECT * FROM sales_data |
You can disable individual prompts by setting their enabled flag to false:
Or disable all prompts globally:
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.
A ready-to-use MCP configuration file is provided at mcp-servers-config.json that can be used with LLM clients to connect to this Druid MCP server.
The configuration includes both transport options:
More details on this on examples/stdio/README.md.
More details on this on examples/sse/README.md.
This repository includes comprehensive examples to help you get started with different deployment scenarios and transport modes:
Complete Docker Compose configuration for running a full Apache Druid cluster locally. Perfect for development, testing, and learning about Druid cluster architecture.
Features:
Configuration examples for STDIO (Standard Input/Output) transport mode - the recommended method for integrating with LLM clients like Claude Desktop.
Features:
Configuration examples for running the Druid MCP Server using Docker with STDIO transport mode. This approach combines the convenience of Docker deployment with STDIO transport for LLM client integration.
Features:
Configuration examples for SSE (Server-Sent Events) transport mode, providing HTTP-based communication suitable for web applications and REST API integrations.
Features:
This Druid MCP Server is part of a comprehensive ecosystem of Apache Druid tools and extensions developed by iunera. These complementary projects enhance different aspects of Druid cluster management and data ingestion:
Advanced configuration management and deployment tools for Apache Druid clusters. This project provides:
Integration with Druid MCP Server: The cluster configurations provided by this project work seamlessly with the monitoring and management capabilities of the Druid MCP Server, enabling comprehensive cluster lifecycle management.
A specialized Apache Druid extension for ingesting and analyzing code-related data and metrics. This extension enables:
Integration with Druid MCP Server: This extension expands the ingestion capabilities that can be managed through the MCP server's ingestion management tools, providing specialized support for code analytics use cases.
This Druid MCP Server is developed and maintained by iunera, a leading provider of advanced AI and data analytics solutions.
iunera specializes in:
As veterans in Apache Druid iunera deployed and maintained a large number of solutions based on Apache Druid in productive enterprise grade scenarios.
For more information about our services and solutions, visit www.iunera.com.
Need help? Let
© 2024 iunera. Licensed under the Apache License 2.0.
This server cannot be installed
Natural Language Analytics MCP server for Apache Druid. With this enterprise ready server in Java, one can query Apache Druid by natural language queries. Furthermore, the complete management like data loading of the Time Series Database Druid can be done with natural language commands.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/iunera/druid-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server