doris-mcp
Provides read-only tools for Apache Doris, covering database/table metadata discovery, read-only SQL execution, EXPLAIN plans and query profiles, cluster and compaction status, active query tasks, ingestion/load status, and UDF listing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@doris-mcp what tables are in the ods database, and how big is ods_orders?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
doris-mcp
Apache Doris 的只读 MCP Server,适配版本:doris-1.2.4-1-Unknown。
提供 17 个只读工具,覆盖库表元数据、只读 SQL、执行计划、集群与导入状态。
环境要求
Python ≥ 3.12(项目已带
.python-version)uv(负责 Python 版本与依赖)
Related MCP server: mcp-read-only-sql
初始化与运行
1. 安装 uv(已装可跳过)
# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh2. 初始化环境
cd doris-mcp # 进入本项目目录(路径随你放置的位置)
uv python install 3.12 # 安装项目所需 Python(已有可跳过)
uv sync # 创建 .venv 并按 uv.lock 安装依赖(含 dev 组)uv sync 会自动创建 .venv,不需要手动 venv/pip。如需在 shell 里直接用命令:
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate3. 配置连接
cp .env.example .env # 然后按实际环境改 .env或用 CLI 参数直连(参数优先级高于环境变量):
uv run doris-mcp --doris-host 10.0.0.10 --doris-port 9030 \
--doris-user readonly_user --doris-password '***' \
--doris-database your_db4. 验证
uv run doris-mcp --version
uv run doris-mcp --help
uv run python scripts/smoke.py --db <db> --table <tbl> # 逐个调用 17 个工具默认 stdio 传输,由 MCP 宿主拉起;直接命令行运行会等待协议输入,属正常现象。
提供的工具(17 个,全部只读)
元数据
工具 | 用途 | 数据源 |
| 连通性、版本、默认库、能力剖面 |
|
| catalog 清单 |
|
| 库清单,可指定 catalog, |
|
| 表清单,支持 |
|
| 字段名/类型/是否 key/默认值/聚合类型/注释;可选引擎行数、建表 DDL、索引 |
|
| 库内各表大小;指定表则汇总分区 |
|
| 分区清单 + 数据新鲜度滞后 |
|
| 跨 catalog 浏览库表 |
|
查询
工具 | 用途 | 数据源 |
| 执行只读 SQL | 原样执行(SELECT/SHOW/DESC/EXPLAIN/WITH) |
| 执行计划, |
|
| 单个查询的 profile |
|
集群
工具 | 用途 | 数据源 |
| FE/BE 节点、容量、库表统计、库容量(FE 取不到时降级只给 BE) |
|
| 按 tablet 统计版本堆积,判断 compaction 落后 |
|
| 当前正在跑的查询 |
|
| 哪些语法在 1.2 上可用(可开 | 内置能力矩阵 |
导入
工具 | 用途 | 数据源 |
| 导入任务状态与失败原因 |
|
| 自定义函数清单, |
|
分页与返回结构
三个列表工具(doris_list_databases / doris_list_tables / doris_list_udfs)统一返回分页信封:
{"ok":true,"total":120,"count":50,"offset":0,"limit":50,
"items":[{"name":"ods_orders","type":"BASE TABLE"}],
"has_more":true,"next_offset":50}翻下一页:把
next_offset当作offset再调一次;has_more=false表示到底internal catalog 走
information_schema(schemata / tables)在服务端分页—— 1.2 的SHOW DATABASES/SHOW TABLES不支持LIMIT指定其他 catalog 时用
SHOW ... FROM,取回后本地切页,items[].type为null
工具注解
17 个工具都带 MCP annotations:readOnlyHint=true、destructiveHint=false、
idempotentHint=true、openWorldHint=true,并各有一个中文 title,宿主可据此判断工具性质。
典型问法
"这个库有哪些表" →
doris_list_databases→doris_list_tables"这表有哪些字段、注释是什么" →
doris_describe_table"这张表多大、多少个分区、数据新不新" →
doris_get_table_size/doris_get_table_partitions"这条 SQL 为什么慢" →
doris_explain_query(format="graph"),需要细节时doris_get_query_profile"现在有谁在跑查询" →
doris_list_active_tasks"集群几台机器、磁盘够不够" →
doris_get_cluster_overview"某个 SQL 语法能不能用" →
doris_get_runtime_capabilities
只读保证
写语句(ALTER / INSERT / UPDATE / DELETE / DROP / TRUNCATE / SET GLOBAL /
INTO OUTFILE / KILL …)在碰数据库之前就被沙箱拒绝,返回 invalid_argument;
doris_explain_query 也只接受只读 SQL。
只读是硬编码策略,没有放开写的环境变量或开关。改表结构、改注释请用别的客户端在 Doris 侧执行。
配置
优先级:CLI 参数 > 环境变量 > .env > 默认值。
变量 | 默认 | 说明 |
|
| FE 的 MySQL 协议地址 |
|
| 建议用只有 |
| 空 | 默认库 |
|
| 单次返回行数上限(硬上限) |
|
| 单次返回字节上限 |
|
| 建连超时(秒) |
|
| 查询超时(秒) |
|
| 连接池大小 |
|
| 传输层重试次数(2013/10054),0 表示不重试 |
|
|
|
|
| HTTP 模式 |
|
| 日志只写 stderr |
接入 MCP 宿主
推荐:把 CLI 装到 PATH,配置里就不用写任何路径。在项目目录执行一次:
uv tool install . # 安装 doris-mcp 命令(依赖隔离,与项目 .venv 无关)
doris-mcp --version # 能打印版本即可stdio(Claude Desktop / Cherry Studio / Cline 等):
{
"mcpServers": {
"doris": {
"command": "doris-mcp",
"args": ["--transport", "stdio"],
"env": {
"DORIS_HOST": "10.0.0.10",
"DORIS_PORT": "9030",
"DORIS_USER": "readonly_user",
"DORIS_PASSWORD": "***",
"DORIS_DATABASE": "your_db"
}
}
}
}如果不想安装,也可以让宿主用 uv 拉起,把 ./doris-mcp 换成你放置本项目的相对或绝对路径:
"command": "uv",
"args": ["--directory", "./doris-mcp", "run", "doris-mcp", "--transport", "stdio"]宿主的启动工作目录通常不是你的 shell 目录,相对路径可能解析不到;这种情况下 用上面的
uv tool install方式更稳。
HTTP:
uv run doris-mcp --transport http --port 3000
# 端点:http://127.0.0.1:3000/mcp返回格式
所有工具返回紧凑 JSON,从不抛异常(MCP 层会把异常包成 UnexpectedToolError,真实原因会丢)。
{"ok":true,"sql":"SHOW DATABASES","columns":[{"name":"Database","type":"VAR_STRING"}],
"rows":[["cloud"]],"row_count":1,"truncated":false,"elapsed_ms":3}失败时 ok:false,error 里带 code 与 hint:
{"ok":false,"sql":"SHOW BACKENDS","target":"root@h:9030/cloud",
"error":{"type":"sql_error","code":1064,"message":"...",
"hint":"当前连接 Doris version doris-1.2.4-1-Unknown。Doris 1.2 常见 2.0+ 语法不兼容:..."}}1.2 使用注意
以下差异在 doris-1.2.4-1-Unknown 上实测,写 SQL 时容易踩:
表大小用
SHOW DATA,必须先USE db;SHOW DATA FROM db报 unknown table分区用
SHOW PARTITIONS FROM db.tbl(17 列,含DataSize/VisibleVersionTime)节点信息:
SHOW FRONTENDS、information_schema.backends(列名是IP)UDF 用
SHOW FUNCTIONS;SHOW GLOBAL FUNCTIONS是语法错误profile 是
SHOW QUERY PROFILE "/id",path 必须带/前缀当前查询用
SHOW PROC '/current_queries';没有/slow_queries,也没有审计表不支持
mv_infos()/jobs()/SHOW WORKLOAD GROUPS/COUNT(DISTINCT x)并行度变量是
parallel_fragment_exec_instance_num
不确定某条语法能不能用,先查 doris_get_runtime_capabilities(内置 19 项支持 / 6 项不支持)。
已知限制
doris_execute_query超出max_rows时不读取剩余结果,直接丢弃该连接(避免SELECT *把百万行拉进内存), 代价是大结果查询多一次建连。查询超时只中断本进程的等待,Doris 侧语句可能仍在跑;要彻底终止请在 Doris 侧
KILL。只读守卫是"够用级"而非完备级:生产环境请给 MCP 配一个只有
SELECT_PRIV的 Doris 账号。连接层有三层兜底:复用前
COM_PING、传输层重试、诊断查询 15s 短超时。 若出现大面积2013/10054,先跑scripts/diagnose_connection.py判断是网络还是 Doris。
开发
uv sync # 含 dev 依赖(pytest / ruff)
uv run pytest # 85 个用例,不需要数据库
uv run python scripts/probe.py # 探测实例方言,输出 OK/UNSUPPORTED
uv run python scripts/smoke.py --db <db> --table <tbl> # MCP 客户端实测 17 个工具
uv run python scripts/diagnose_connection.py # 连接稳定性诊断probe.py 支持 PROBE_DB / PROBE_TABLE 追加表级检查。
说明
本项目是面向 Doris 1.2 的社区实现,与 Apache Doris 项目及官方 doris-mcp-server 无隶属关系。
只在 doris-1.2.4-1-Unknown 上做过完整验证,其他版本的行为未经测试。
许可证
Available Tools
17 toolsdoris_describe_tableARead-onlyIdempotent
查看表结构:字段名、类型、是否可空、是否 key 列、默认值、Extra(聚合类型等)、注释。 注释取自 SHOW FULL COLUMNS —— 1.2 上最完整的列元数据来源。 include_basic 用 SHOW TABLE STATUS 补引擎/行数/创建时间(官方 get_table_context 的 basic 段)。
Inputs: table (required), database (required), include_ddl, include_basic, +1 more. Returns: result
doris_execute_queryARead-onlyIdempotent
执行只读 SQL 并返回列与行。非 SELECT/SHOW/DESC/EXPLAIN/WITH 一律拒绝, 本服务没有任何写通道。结果超出 max_rows 时 truncated=true。
Inputs: sql (required), database, max_rows. Returns: result
doris_explain_queryARead-onlyIdempotent
看执行计划:EXPLAIN / EXPLAIN VERBOSE / EXPLAIN GRAPH。 graph 输出 ASCII 执行图,排查 join/scan 分布最直观(1.2 实测可用)。
Inputs: sql (required), format, database. Returns: result
doris_get_cluster_overviewARead-onlyIdempotent
集群概览:FE 节点(SHOW FRONTENDS)、BE 节点(information_schema.backends)、 库表统计(SHOW PROC '/statistic')、库容量(SHOW PROC '/dbs')。 FE 查询给短超时,取不到就降级为只给 BE,不阻塞整体返回。
Inputs: include_nodes. Returns: result
doris_get_compaction_statusARead-onlyIdempotent
排查 compaction 落后:按 tablet 统计 rowset(版本)数量(information_schema.rowsets)。 单个 tablet 的 rowset 数持续偏高说明 compaction 跟不上写入。
Inputs: top_n. Returns: result
doris_get_ingestion_statusBRead-onlyIdempotent
导入任务状态:SHOW LOAD(17 列,Broker/Routine 一次性导入)与 SHOW ROUTINE LOAD(19 列,常驻例行导入)。默认两类都给。
Inputs: kind, limit, database. Returns: result
doris_get_query_profileARead-onlyIdempotent
取某个查询的 profile(SHOW QUERY PROFILE "/id")。只对执行过的 query id 有效, 取不到时 Doris 返回 1105 not found。
Inputs: query_id (required). Returns: result
doris_get_runtime_capabilitiesARead-onlyIdempotent
返回当前实例的能力矩阵(1.2 实测结论):哪些语法可用、哪些会挂死或不存在。 写 SQL 前先查一次,能避免用 2.0+ 语法踩坑。probe=true 时附带实时抽查结果。
Inputs: probe. Returns: result
doris_get_table_partitionsARead-onlyIdempotent
看分区清单与数据新鲜度(SHOW PARTITIONS,17 列)。 VisibleVersionTime 是分区最新可见版本时间,用它算滞后(官方 monitor_data_freshness)。
Inputs: table (required), database (required). Returns: result
doris_get_table_sizeARead-onlyIdempotent
看表/库的数据量。不传 table:SHOW DATA(必须先选库,返回每表 Size + ReplicaCount)。 传 table:SHOW PARTITIONS 汇总 DataSize,给出总字节数与分区数。
Inputs: database (required), table. Returns: result
doris_inspect_external_catalogARead-onlyIdempotent
浏览 catalog:只传 catalog 时列库(SHOW DATABASES FROM c); 带 database 时列表(SHOW TABLES FROM c.db)。
Inputs: catalog (required), database. Returns: result
doris_list_active_tasksARead-onlyIdempotent
当前正在执行的查询(SHOW PROC '/current_queries',7 列)。空结果表示当前无活跃查询。
Inputs: no named parameters. Returns: result
doris_list_catalogsARead-onlyIdempotent
列出 catalog(SHOW CATALOGS,1.2 可用,4 列)。
Inputs: no named parameters. Returns: result
doris_list_databasesARead-onlyIdempotent
列出数据库,分页返回。
internal:走 information_schema.schemata(1.2 的 SHOW DATABASES 不支持 LIMIT,
这里在服务端分页);指定其他 catalog 时用 SHOW DATABASES FROM,取回后本地切页。
返回:{ok, total, count, offset, limit, items[{name}], has_more, next_offset, source}
Inputs: limit, offset, catalog. Returns: result
doris_list_tablesARead-onlyIdempotent
列出某个库下的表,分页返回,并区分表与视图。
internal:走 information_schema.tables(1.2 的 SHOW TABLES 不支持 LIMIT),
WHERE TABLE_SCHEMA + 可选 LIKE 在服务端过滤;其他 catalog 用 SHOW TABLES FROM,
取回后本地切页。
返回:{ok, total, count, offset, limit, items[{name, type}], has_more, next_offset, source}
Inputs: database (required), limit, offset, catalog, +1 more. Returns: result
doris_list_udfsARead-onlyIdempotent
列出 UDF,分页返回。
SHOW FUNCTIONS 在 1.2 不支持 LIMIT,也不支持 SHOW GLOBAL FUNCTIONS(语法错误),
且要求连接已选库;因此取回后在本地切页(UDF 数量有限,代价可忽略)。
返回:{ok, total, count, offset, limit, items[{name}], has_more, next_offset}
Inputs: limit, offset, database, name_like. Returns: result
doris_pingARead-onlyIdempotent
检查连通性并返回 Doris 版本、默认库、服务器时间与结果限制。连通性排查的第一步。
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target a distinct resource: catalog/db/table metadata, query execution, monitoring, ingestion status. However doris_inspect_external_catalog overlaps with doris_list_databases and doris_list_tables (it lists dbs when given a catalog, tables when given a db), and doris_get_table_size without a table also returns per-table sizes like SHOW DATA, so an agent could reasonably pick the wrong one. Descriptions help but the boundaries are not fully crisp.
Every tool uses the doris_ prefix plus a consistent verb_noun pattern (list_databases, get_table_size, describe_table, execute_query, explain_query), with only doris_ping as a conventional noun-only exception. No mixed casing or verb-style drift.
17 tools is on the high side, but each covers a distinct Doris administration surface (metadata, query profiling, ingestion, cluster health, compaction). No obvious filler tools, though a couple of metadata tools could plausibly be merged.
Strong coverage for a deliberately read-only server: connectivity/capability probing, catalog-db-table-column metadata, sizes and partitions, query execution/explain/profile, active tasks, ingestion, cluster and compaction health. Notable gaps are operational actions like killing a runaway query, session variable inspection, and user/permission metadata.
Maintenance
Related MCP Connectors
Governed SQL access to your databases: redaction, query review and an audit log.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Query your own databases and Data Sets with read-only SQL, and build hosted dashboards.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables secure read-only access to PostgreSQL databases through SELECT queries only, with tools for exploring schemas, listing tables, and executing common queries while preventing any data modification operations.MIT
- AlicenseNot gradedqualityBmaintenanceProvides secure read-only SQL access to PostgreSQL and ClickHouse databases with built-in safety features like read-only enforcement, timeouts, and managed result files.241 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceEnables safe interaction with PostgreSQL databases through read-only queries, schema exploration, and performance analysis.144 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables read-only SQL querying and schema inspection across MSSQL, PostgreSQL, and MySQL databases via MCP tools.ISC