Doris MCP Server

Apache Doris MCP 服务

English | 简体中文

Apache Doris MCP 服务通过 MCP 2026-07-28，向 MCP Host 和 AI Agent 提供 Apache Doris 的只读能力。1.0 版以 8 个稳定领域和 55 项逐步披露的子能力，取代了庞大扁平的工具集，同时明确说明运行时可用性、授权、输入架构、输出架构和故障行为。

发布状态

软件包版本为 1.0.0。master 分支上的 MCP 2026-07-28 协议兼容性，在 Streamable HTTP 和 stdio 上均为 正式发布（GA）。 此 GA 声明仅针对协议兼容性；Python 软件包的分类仍为 Beta，且仍适用文档中说明的部署限制。

升级前，请阅读 1.0 发布说明、1.0 迁移指南以及生成的 8 个领域／55 项子能力注册表。详细发布记录见 Issue #189。

架构概览

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

默认的 hierarchical 模式会公开以下领域：

领域	子项	职责
doris_catalog	5	目录、数据库、表、表上下文、大小
doris_query	7	查询、解释、分析配置、诊断、慢查询、显式 ADBC
doris_cluster	11	节点、任务、指标、内存、缓存、压实、工作负载
doris_pipeline	5	数据摄取、物化视图、新鲜度、依赖项
doris_search	4	文本／向量／混合搜索、分析器、索引、诊断
doris_governance	8	质量、存储、血缘、审计、UDF、授权映射
doris_lakehouse	3	外部目录、Lakehouse 表、Variant
doris_semantic	12	可选的 Apache Ossie grounding 和 MetricFlow 消费

使用 {} 调用某个领域，以发现已授权的子项和精确架构。 再次调用同一领域时，需传入 child_tool、arguments 和返回的 manifest_version。 无法使用渐进式披露的 Host 可在启动前设置 MCP_TOOL_EXPOSURE_MODE=flat；此设置会以无名称冲突的正式名称公开相同的 55 项子能力，不会恢复 1.0 之前的别名。

请参阅架构、请求生命周期和工具领域。

快速开始

要求：

• Python 3.12 或更高版本；
• Apache Doris 2.0.0 或更高版本；
• 可访问 Doris FE MySQL 端点的网络，通常使用端口 9030。

安装固定版本：

pip install doris-mcp-server==1.0.0

doris-mcp-server 用于启动服务。doris-mcp-client 是独立的客户端；这两个命令不能互换使用。

配置 Doris 路由：

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=mcp_reader
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

在环回地址上启动 Streamable HTTP：

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

端点：

• MCP：POST http://127.0.0.1:3000/mcp
• 旧版 MCP（选择启用）：POST http://127.0.0.1:3000/mcp/legacy
• 存活状态：GET http://127.0.0.1:3000/live
• Doris 就绪状态：GET http://127.0.0.1:3000/ready

仅支持握手阶段 Streamable HTTP 的 Host（包括使用 MCP 2025-06-18 的 Dify 1.16.1）必须设置 ENABLE_LEGACY_HTTP_ADAPTER=true 并连接到 /mcp/legacy。该适配器仅更改协议边界；它保留相同的 1.0 工具、授权、能力门控和只读执行模式。

或者，为本地 Host 运行 stdio：

doris-mcp-server --transport stdio

请参阅完整的快速开始和 Host 集成指南。

安全边界

• 内置的 1.0 目录为只读；doris_admin 已预留且未注册。
• 支持静态令牌、JWT、外部 OAuth/OIDC 和由 Doris 支持的 OAuth，并采用相互验证的配置边界。
• 域发现和子级执行使用精确的授权标识符。
• Doris RBAC 仍是可见对象和数据的最终权威。
• SQL 结构、标识符、参数、超时、行数、字节数和结果架构均会在数据离开 Server 前受到限制。
• 公共结果和日志中的机密信息及后端错误均会被隐藏。
• 非环回 HTTP 需要身份验证，除非启用了明确的危险开发覆盖选项。

请阅读安全与权限模型和Doris 精细化访问指南。

可靠性边界

Server 使用确定性清单和错误、带签名且会过期的游标、感知路由的功能快照、有界的过期回退、特定于请求的连接路由、多 FE 故障转移、存活性与就绪状态分离、输出架构验证，以及经过净化的跟踪信息传播。不受支持或配置错误的功能仍可被发现，其 callable=false，调用时则会默认拒绝。

当前限制包括：由 Doris 支持的 OAuth 仅限进程内；ADBC 仅在显式启用时使用，默认禁用，并且在基于令牌的路由上会默认拒绝；可选的只读 Ossie grounding；可选的 MetricFlow 编译器 sidecar，其 SQL 必须通过有界的 MCP 查询运行时执行；以及尽力而为的原生血缘信息传递。请参阅可靠性与限制。

文档

根目录中的 README 刻意仅作为入口。双语文档系统的索引位于：

• 英文文档
• 简体中文文档

主要指南：

• 架构
• 请求和数据流
• 工具域
• 功能可用性
• Doris 版本功能矩阵
• MetricFlow 集成
• MCP 2026-07-28 契约
• 安全模型
• 部署
• 可靠性与限制
• 故障排除
• 配置参考
• 主机集成
• 自定义工具提供方
• 参与贡献

开发

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

生成的制品必须保持同步：

uv run python generate_tool_catalog.py --check
uv lock --check

请参阅贡献与验证。

许可证

Apache License 2.0。请参阅 LICENSE.txt 和 NOTICE。