Druid MCP Server

Druid MCP

此仓库提供一个 MCP（Model Context Protocol）服务，可对一个或多个 Apache Druid 集群进行全面的只读访问，用于临时数据分析、监控、故障排查和比较。

例如，如果你有多个环境，每个环境都有自己的 Druid 集群，但这些集群都从同一来源摄取数据，那么你可以使用类似下面的简单提示词来执行复杂的跨集群比较：

检查并比较所有 Druid 集群中 SumUp 的数据源。

随后，AI Agent 应自行列出 Druid 集群及其数据源，探索其架构、分段、任务和数据分布，最终为你提供一份清晰的摘要。

概述

Druid MCP 服务支持 AI 应用通过 Model Context Protocol（MCP）与 Apache Druid 交互。它提供了用于查询和探索 Druid 数据源的标准化接口，让你轻松将 Druid 数据集成到 AI 工作流中。

功能

• 多集群支持：同时连接并查询多个 Druid 集群
• 查询执行：SQL 和原生 JSON 查询
• 数据源管理：列出、探索和检查数据源架构
• 数据摄取监控：跟踪 Supervisor 和任务状态
• 集群操作：监控服务健康状态并分析分段
• Lookup 管理：查询和检查 Lookup 表
• 智能分析提示词：为常见数据分析任务预置提示词
• 架构缓存：仅在资源中使用 5 分钟 TTL 高效缓存，以提升性能

前置条件

• Python 3.11+
• 能够访问 Apache Druid 集群
• 兼容 MCP 的客户端（例如 Claude Desktop）

安装

使用 uv 安装依赖：

uv install

或使用 pip：

pip install -e .

配置

多集群支持

使用空格分隔的 key=value 键值对配置多个 Druid 集群：

# Define available clusters (optional, defaults to "localhost=http://localhost:8088")
export DRUID_CLUSTER_URLS="localhost=http://localhost:8088 dev=https://druid.dev.example.com prod=https://druid.prod.example.com"

集群名称可以是任何有效字符串，并用于：

• 资源 URI（例如，druid://dev/v2/datasources）
• 工具参数（例如，execute_sql_query("dev", "SELECT ...")）
• 集群管理命令

使用方法

开发模式

使用自动重新加载运行，以便开发：

mcp dev main.py

生产模式

在生产环境中运行服务：

mcp run main.py

Claude Desktop 集成

安装服务以便与 Claude Desktop 配合使用：

mcp install main.py

可用工具

MCP 服务提供 16 个工具，按功能分类如下：

重要：除集群管理工具外，所有工具都要求将显式的 cluster 参数作为第一个参数。这样无需管理状态即可高效执行多集群操作。

查询执行

• execute_sql_query(cluster, query, context)：执行 SQL 查询
• execute_native_query(cluster, query)：执行原生 JSON 查询（timeseries、topN、groupBy 等）

数据源操作

• list_datasources(cluster, include_details)：列出所有可用数据源
• get_datasource_schema(cluster, datasource)：获取数据源的维度和指标

数据摄取监控

• list_supervisors(cluster, include_state)：列出所有 Supervisor，并可选择包含状态信息
• get_supervisor_status(cluster, supervisor_id)：获取 Supervisor 的详细状态和健康情况
• list_tasks(cluster, ...)：列出任务，并可选择筛选条件
• get_task_status(cluster, task_id)：获取指定任务的状态

集群管理

• get_cluster_status(cluster)：获取集群整体健康状态
• list_services(cluster, service_type)：按类型列出活动服务
• list_segments(cluster, datasource, full)：列出数据源的分段
• get_segments_info(cluster, datasource)：获取汇总的分段统计信息

Lookup 管理

• list_lookups(cluster, tier)：按 tier 列出 Lookup
• get_lookup(cluster, lookup_id, tier)：获取指定 Lookup 的配置
• get_lookup_status(cluster, lookup_id, tier)：获取各节点上的 Lookup 加载状态

多集群管理

• list_clusters()：列出所有已配置的 Druid 集群名称

分析提示词

5 个预构建提示词，具有智能默认设置（从上个月到现在）：

• analyze_time_range：分析指定时间段内的数据
• explore_datasource：探索数据源结构和内容
• monitor_ingestion：监控摄取状态和进度
• compare_periods：比较不同时间段的指标
• data_quality_check：执行全面的数据质量检查

示例

基本用法

# List datasources from production cluster
list_datasources("prod")

# Execute SQL query on development cluster
execute_sql_query("dev", "SELECT COUNT(*) FROM wikipedia WHERE __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY")

# Get datasource schema from staging
get_datasource_schema("stage", "wikipedia")

多集群操作

# Compare data across environments
dev_count = execute_sql_query("dev", "SELECT COUNT(*) FROM orders")
prod_count = execute_sql_query("prod", "SELECT COUNT(*) FROM orders")

# Check cluster health across all environments
for cluster in ["dev", "stage", "prod"]:
    status = get_cluster_status(cluster)
    print(f"{cluster}: {status}")

# Monitor ingestion across clusters
list_supervisors("dev", include_state=True)
list_supervisors("prod", include_state=True)

高级查询

# Native query with explicit cluster
execute_native_query("prod", {
    "queryType": "timeseries",
    "dataSource": "wikipedia",
    "intervals": ["2024-01-01/2024-01-02"],
    "granularity": "hour",
    "aggregations": [
        {"type": "count", "name": "edits"},
        {"type": "longSum", "name": "added", "fieldName": "added"}
    ]
})

# Complex filtering with multiple parameters
list_tasks("prod", 
    datasource="wikipedia",
    state="running",
    max_tasks=10
)

资源

Druid API 端点以 MCP 资源的形式提供，并支持缓存和多集群：

资源 URI 格式

druid://{cluster}/{path}

可用资源

• druid://localhost/v2/datasources - 列出所有数据源
• druid://localhost/v2/datasources/{name} - 获取数据源架构
• druid://localhost/coordinator/v1/datasources/{name} - Coordinator 信息
• druid://localhost/coordinator/v1/metadata/datasources/{name}/segments - 数据段
• druid://localhost/overlord/v1/tasks - 列出任务
• druid://localhost/overlord/v1/supervisors - 列出监督器
• druid://localhost/status/health - 健康检查

将 localhost 替换为任意已配置的集群名称，即可访问不同环境。

安全性

此 MCP 服务仅提供对 Druid 集群的只读访问。不支持也不允许任何写入操作。

许可证

MIT