Skip to main content
Glama
doris-mcp

doris-mcp

by fhm0520

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 | sh

2. 初始化环境

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/activate

3. 配置连接

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_db

4. 验证

uv run doris-mcp --version
uv run doris-mcp --help
uv run python scripts/smoke.py --db <db> --table <tbl>   # 逐个调用 17 个工具

默认 stdio 传输,由 MCP 宿主拉起;直接命令行运行会等待协议输入,属正常现象。

提供的工具(17 个,全部只读)

元数据

工具

用途

数据源

doris_ping

连通性、版本、默认库、能力剖面

SELECT @@version_comment, ...

doris_list_catalogs

catalog 清单

SHOW CATALOGS

doris_list_databases

库清单,可指定 catalog,limit/offset 分页

SHOW DATABASES [FROM c] / information_schema.schemata

doris_list_tables

表清单,支持 LIKE 过滤与 limit/offset 分页,区分表/视图

SHOW TABLES FROM [c.]db [LIKE] / information_schema.tables

doris_describe_table

字段名/类型/是否 key/默认值/聚合类型/注释;可选引擎行数、建表 DDL、索引

SHOW FULL COLUMNS(+ SHOW TABLE STATUS / SHOW CREATE TABLE / SHOW INDEX)

doris_get_table_size

库内各表大小;指定表则汇总分区 DataSize

SHOW DATA / SHOW PARTITIONS

doris_get_table_partitions

分区清单 + 数据新鲜度滞后

SHOW PARTITIONS

doris_inspect_external_catalog

跨 catalog 浏览库表

SHOW DATABASES FROM c / SHOW TABLES FROM c.db

查询

工具

用途

数据源

doris_execute_query

执行只读 SQL

原样执行(SELECT/SHOW/DESC/EXPLAIN/WITH)

doris_explain_query

执行计划,format=plan/verbose/graph(graph 出 ASCII 执行图)

EXPLAIN / EXPLAIN VERBOSE / EXPLAIN GRAPH

doris_get_query_profile

单个查询的 profile

SHOW QUERY PROFILE "/id"

集群

工具

用途

数据源

doris_get_cluster_overview

FE/BE 节点、容量、库表统计、库容量(FE 取不到时降级只给 BE)

SHOW FRONTENDS + information_schema.backends + SHOW PROC '/statistic' + '/dbs'

doris_get_compaction_status

按 tablet 统计版本堆积,判断 compaction 落后

information_schema.rowsets

doris_list_active_tasks

当前正在跑的查询

SHOW PROC '/current_queries'

doris_get_runtime_capabilities

哪些语法在 1.2 上可用(可开 probe 实时抽查)

内置能力矩阵

导入

工具

用途

数据源

doris_get_ingestion_status

导入任务状态与失败原因

SHOW LOAD / SHOW ROUTINE LOAD

doris_list_udfs

自定义函数清单,limit/offset 分页

SHOW FUNCTIONS

分页与返回结构

三个列表工具(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 > 默认值。

变量

默认

说明

DORIS_HOST / DORIS_PORT

127.0.0.1 / 9030

FE 的 MySQL 协议地址

DORIS_USER / DORIS_PASSWORD

root / 空

建议用只有 SELECT_PRIV 的账号

DORIS_DATABASE

空

默认库

DORIS_MAX_ROWS

200

单次返回行数上限(硬上限)

DORIS_MAX_RESULT_BYTES

1000000

单次返回字节上限

DORIS_CONNECT_TIMEOUT

10

建连超时(秒)

DORIS_QUERY_TIMEOUT

60

查询超时(秒)

DORIS_POOL_SIZE

4

连接池大小

DORIS_RETRIES

2

传输层重试次数(2013/10054),0 表示不重试

MCP_TRANSPORT

stdio

stdio 或 streamable-http

MCP_HOST / MCP_PORT / MCP_PATH

127.0.0.1 / 3000 / /mcp

HTTP 模式

LOG_LEVEL

INFO

日志只写 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 上做过完整验证,其他版本的行为未经测试。

许可证

MIT

Available Tools

17 tools
doris_describe_tableA
Read-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_queryA
Read-onlyIdempotent

执行只读 SQL 并返回列与行。非 SELECT/SHOW/DESC/EXPLAIN/WITH 一律拒绝, 本服务没有任何写通道。结果超出 max_rows 时 truncated=true。

Inputs: sql (required), database, max_rows. Returns: result

doris_explain_queryA
Read-onlyIdempotent

看执行计划:EXPLAIN / EXPLAIN VERBOSE / EXPLAIN GRAPH。 graph 输出 ASCII 执行图,排查 join/scan 分布最直观(1.2 实测可用)。

Inputs: sql (required), format, database. Returns: result

doris_get_cluster_overviewA
Read-onlyIdempotent

集群概览:FE 节点(SHOW FRONTENDS)、BE 节点(information_schema.backends)、 库表统计(SHOW PROC '/statistic')、库容量(SHOW PROC '/dbs')。 FE 查询给短超时,取不到就降级为只给 BE,不阻塞整体返回。

Inputs: include_nodes. Returns: result

doris_get_compaction_statusA
Read-onlyIdempotent

排查 compaction 落后:按 tablet 统计 rowset(版本)数量(information_schema.rowsets)。 单个 tablet 的 rowset 数持续偏高说明 compaction 跟不上写入。

Inputs: top_n. Returns: result

doris_get_ingestion_statusB
Read-onlyIdempotent

导入任务状态:SHOW LOAD(17 列,Broker/Routine 一次性导入)与 SHOW ROUTINE LOAD(19 列,常驻例行导入)。默认两类都给。

Inputs: kind, limit, database. Returns: result

doris_get_query_profileA
Read-onlyIdempotent

取某个查询的 profile(SHOW QUERY PROFILE "/id")。只对执行过的 query id 有效, 取不到时 Doris 返回 1105 not found。

Inputs: query_id (required). Returns: result

doris_get_runtime_capabilitiesA
Read-onlyIdempotent

返回当前实例的能力矩阵(1.2 实测结论):哪些语法可用、哪些会挂死或不存在。 写 SQL 前先查一次,能避免用 2.0+ 语法踩坑。probe=true 时附带实时抽查结果。

Inputs: probe. Returns: result

doris_get_table_partitionsA
Read-onlyIdempotent

看分区清单与数据新鲜度(SHOW PARTITIONS,17 列)。 VisibleVersionTime 是分区最新可见版本时间,用它算滞后(官方 monitor_data_freshness)。

Inputs: table (required), database (required). Returns: result

doris_get_table_sizeA
Read-onlyIdempotent

看表/库的数据量。不传 table:SHOW DATA(必须先选库,返回每表 Size + ReplicaCount)。 传 table:SHOW PARTITIONS 汇总 DataSize,给出总字节数与分区数。

Inputs: database (required), table. Returns: result

doris_inspect_external_catalogA
Read-onlyIdempotent

浏览 catalog:只传 catalog 时列库(SHOW DATABASES FROM c); 带 database 时列表(SHOW TABLES FROM c.db)。

Inputs: catalog (required), database. Returns: result

doris_list_active_tasksA
Read-onlyIdempotent

当前正在执行的查询(SHOW PROC '/current_queries',7 列)。空结果表示当前无活跃查询。

Inputs: no named parameters. Returns: result

doris_list_catalogsA
Read-onlyIdempotent

列出 catalog(SHOW CATALOGS,1.2 可用,4 列)。

Inputs: no named parameters. Returns: result

doris_list_databasesA
Read-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_tablesA
Read-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_udfsA
Read-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_pingA
Read-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

    A3.8/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables safe interaction with PostgreSQL databases through read-only queries, schema exploration, and performance analysis.
      144 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only SQL querying and schema inspection across MSSQL, PostgreSQL, and MySQL databases via MCP tools.
      ISC