mcp-server-dmdb
1-line summary: A read-only MCP server for Dameng DM8 that lets an AI client inspect and query the database over stdio.
Check connectivity (
dm_ping) — verify the DB connection, get server version, instance name, current user, reconnect count, and whether theDM_ALLOW_WRITE/DM_ALLOW_DDLswitches are on.List schemas (
dm_list_schemas) — enumerate all schemas/users accessible to the connected user.Browse tables (
dm_list_tables) — find tables by schema and name keyword, with row-count stats, tablespace, and table comments; supports limit/offset paging.Inspect table structure (
dm_describe_table) — columns (type/length/precision/nullable/default), primary/foreign/unique/check constraints, indexes with included columns, table and column comments, and optional DDL viaSP_TABLEDEF.Run read-only queries (
dm_query) — execute a single SELECT with positional?bind parameters; only SELECT is allowed, results truncated by rows/cell size/total chars, BIGINT values preserved at full precision.Sample data (
dm_table_sample) — pull a few rows (default 5) from a table without writing SQL or worrying about identifier quoting/case.Count rows (
dm_table_count) — exactCOUNT(*)by default, or the cheaper statistics-based estimate.Explain plans (
dm_explain) — get the execution plan viaEXPLAIN FORto check index usage and diagnose slow queries.Search objects (
dm_search_objects) — keyword search across table names, column names, and column comments (including Chinese comments).
All 9 exposed tools are read-only; no dm_execute_dml or dm_execute_ddl is registered in this configuration.
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., "@mcp-server-dmdb 列出 TRADE_MARKET 模式下的所有表"
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.
mcp-server-dmdb
达梦 DM8 的 MCP server,基于官方 dmdb Node.js 驱动,用 TypeScript 实现。默认纯只读,写操作与改表结构分别由环境变量开关控制,未开启时对应工具根本不会注册。
安装
npm install -g mcp-server-dmdb@latest # 全局安装最新版
npx -y mcp-server-dmdb@latest # 或按需临时拉取最新版,不落盘@latest 始终拉取 npm 上最新的已发布版本(每次 npm publish 后自动生效),不锁具体版本号。
要求 Node >= 20(ESM only),无原生编译步骤。
Related MCP server: mcp-dm8-server
接入 MCP 客户端
在客户端的 MCP 配置里加一条:
{
"mcpServers": {
"dmdb-dev": {
"command": "npx",
"args": ["-y", "mcp-server-dmdb@latest"],
"env": {
"DM_HOST": "your-host",
"DM_PORT": "5236",
"DM_USER": "your-user",
"DM_PASSWORD": "your-password",
"DM_SCHEMA": "your-schema",
"DM_ALLOW_WRITE": "false",
"DM_ALLOW_DDL": "false"
}
}
}
}Windows 注意:MCP 客户端用 Win32
spawn启动进程,npx是.cmd包装脚本,常解析失败而表现为"客户端静默无响应"。建议改成直接指向node.exe和已安装包的绝对路径:{ "command": "C:/Program Files/nodejs/node.exe", "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/mcp-server-dmdb/dist/index.js"] }先
npm install -g mcp-server-dmdb@latest装最新版,再用npm root -g确认上方路径。Linux / macOS 上npx写法没问题。
使用
按上文配好
DM_*连接信息。客户端以 stdio 方式启动本进程,自动完成
initialize握手并拉取tools/list。调用工具:默认 9 个只读工具;设
DM_ALLOW_WRITE=true出现dm_execute_dml,再设DM_ALLOW_DDL=true出现dm_execute_ddl,共 11 个。排查连接:先用
dm_ping确认连通性与两个写开关的运行时状态。
进程以本地子进程方式运行,凭据通过环境变量注入,不监听任何网络端口,无外部鉴权面。
支持的 MCP 协议
本 server 兼容 MCP(Model Context Protocol)2025-era 规范,基于官方 TypeScript SDK v2 实现。
维度 | 说明 |
传输方式 | stdio(标准输入/输出)。stdout 为 JSON-RPC 2.0 通道,所有日志走 stderr,避免污染协议流导致客户端静默卡死 |
SDK |
|
协议版本 |
|
能力声明 | 仅 |
工具调用 | JSON-RPC |
结果格式 | 以 |
连接模型 | 每次 stdio 连接对应一个独立 |
生命周期 | 捕获 |
兼容性边界
支持:stdio 传输、2025-06-18 握手、工具发现与调用、结构化输出(
outputSchema/structuredContent)。不支持:
SSE / Streamable HTTP 传输(仅 stdio);
OAuth 等网络鉴权(凭据由环境变量注入,进程本地运行,不暴露端口);
资源(
resources)订阅、提示模板(prompts)、服务端主动日志推送(logging通知)。
环境变量
变量 | 默认值 | 说明 |
|
| 数据库地址 |
|
| 端口 |
| 必填 | 用户名 |
| 必填 | 密码 |
| 无 | 登录 schema |
|
| 开启 |
|
| 开启 |
|
| 单次返回行数上限 |
|
| 硬顶, |
|
| 单个单元格字符上限 |
|
| 单次响应总字符上限 |
|
| 连接超时 |
|
| 网络超时(驱动原生) |
|
| JS 层兜底超时,触发即丢弃并重建连接 |
|
| 探活超时 |
| 自动 | 见下文"连接加密" |
|
|
|
|
|
|
工具清单
默认注册 9 个;DM_ALLOW_WRITE=true 加第 10 个;再开 DM_ALLOW_DDL=true 共 11 个。
工具 | 用途 | 开关 |
| 连接自检、服务端版本、实例信息、两个写开关的当前状态 | — |
| 列出可访问的模式 | — |
| 按模式 + 表名关键字列模糊搜表,带行数与表注释 | — |
| 列定义 + 主键/外键/唯一/检查约束 + 索引及包含列 + 注释 + 可选 DDL | — |
| 只读 SELECT,绑定参数 | — |
| 采样看数据,自动处理标识符引号与大小写 | — |
| 精确 | — |
| 执行计划 | — |
| 按关键字搜表名/列名/列注释(支持中文注释) | — |
| INSERT / UPDATE / DELETE,结构化入参 |
|
| CREATE / ALTER / DROP |
|
安全边界
SQL 语句必须连续通过五层检查才会执行,任一层失败即拒绝:
归一化 —— 词法扫描剥离注释(不误伤字符串字面量内的
--和/* */)顶层切分 —— 分号必须位于末尾,否则拒绝。服务端本身不拦多语句:
SELECT 1; SELECT 2会被归类为 PL/SQL 块,只能靠这一层关键字黑名单 —— 在已抹平字符串字面量的文本上按词边界匹配
服务端判定 ——
getStatementInfo()返回的语句类型;异常或缺失一律 fail-closed交叉裁决 —— 第 3 层与第 4 层结论必须一致
永久禁止(任何开关状态下都不放行):
TRUNCATE(DDL 语句;LISTAGG ... ON OVERFLOW TRUNCATE 溢出子句中的关键字不算,见 issue #1)、DROP DATABASE/USER/SCHEMA/TABLESPACE/ROLE、ALTER DATABASE/SYSTEM/SESSION、SHUTDOWN、GRANT、REVOKE、SP_*、SF_*、DBMS_*、EXECUTE IMMEDIATE。
DDL 额外三道锁:
上面的永久黑名单
DROP TABLE/VIEW/INDEX/SEQUENCE与ALTER TABLE ... DROP COLUMN必须传confirm,值严格等于DROP <对象名>每条 DDL 写审计日志(stderr,不受
DM_LOG_LEVEL影响)
DML 保护:update/delete 强制要求 where;autoCommit=false 执行 → 超 max_rows_affected 即回滚,否则提交;建议先用 dry_run=true 统计命中行数。
达梦的 DDL 隐式提交,包不进事务,无法回滚。
已知行为与坑
连接加密默认关闭
dmdb 的 loginEncrypt 默认为 true,但其加密套件在 Node 17+ 的 OpenSSL 3 下会被拒绝:
errCode 6071 消息加密失败
error:0308010C:digital envelope routines::unsupported所以默认改为 false(想强制加密可显式设 DM_LOGIN_ENCRYPT=true)。本驱动只暴露 true/false,不能指定套件。
BIGINT 精度
DM8 的 BIGINT 主键普遍超过 2^53,驱动的默认 number 转换会静默抹平末三位:
真实值 1989221485636136962 -> 到达 JS 时变成 1989221485636137000fetchAsString: [dmdb.NUMBER] 修不了——DM8 里 BIGINT 与 NUMBER 是不同类型。本实现在检测到不安全整数后,只把出问题的那几列用字符串重读一次,因此正常数值列仍是数字,而 ID 保持完整精度。
分页
DM8 原生支持 LIMIT ? OFFSET ? 且可绑定参数(官方实测执行计划优于 ROWNUM/TOP)。dm_query 要求分页写在 SQL 里、值放 params,服务端不做子查询包装——包装会包不住 WITH CTE。
执行计划要用 EXPLAIN FOR
裸 EXPLAIN <sql> 不返回结果集,只回 rowsAffected。必须用 EXPLAIN FOR <sql>。也因此 EXPLAIN 不接受绑定参数,dm_explain 会把 params 安全地内联为字面量。
行数统计
ALL_TABLES.NUM_ROWS 来自统计信息,多数库未收集,值为 NULL。不要拿 dm_list_tables 里的 NUM_ROWS 当真实行数,用 dm_table_count。
语句类型码
getStatementInfo() 返回的是达梦内部码,与 dmdb 自带 .d.ts 声明的 STMT_TYPE_*(声称 SELECT=1)完全不同。实测值:
语句 | 码 | 语句 | 码 |
SELECT(含 FOR UPDATE) | 160 | DROP TABLE | 139 |
INSERT | 157 | ALTER TABLE | 146 |
UPDATE | 159 | TRUNCATE | 194 |
DELETE | 158 | EXPLAIN | 149 |
MERGE | 164 | COMMIT / ROLLBACK | 147 / 148 |
CREATE TABLE | 129 | SET SCHEMA | 153 |
CREATE VIEW / INDEX / SEQ | 131 / 133 / 196 | CALL / BEGIN / 多语句 | 162 |
SELECT ... FOR UPDATE 与普通 SELECT 同为 160,所以 FOR UPDATE 只能靠关键字拦截。
标识符大小写
实测环境中标识符大小写不敏感,data_after_sale 与 DATA_AFTER_SALE 都能命中。但这取决于服务端 CASE_SENSITIVE 参数,不是 DM8 的保证,所以字典查询一律用 UPPER(...) = UPPER(?) 比较。
开发
git clone https://github.com/SpringDamon/mcp-server-dmdb.git
cd mcp-server-dmdb
npm install
npm run build # tsc -> dist/
npm test # 构建 + node --test 跑门禁用例(49 条)下面两个脚本要连真实库,凭据只从环境变量读取,缺失即报错(见 scripts/env.mjs):
export DM_HOST=<host> DM_USER=<user> DM_PASSWORD=<pwd> DM_SCHEMA=<schema>
node scripts/probe-connect.mjs # 验证数据库连通性
node scripts/verify-dict.mjs # 导出字典视图真实列名
node scripts/e2e-mcp.mjs # 端到端 JSON-RPC 验证(45 项检查)依赖
运行时只有 3 个,刻意保持最小:
依赖 | 版本 | 说明 |
|
| MCP SDK v2,ESM-only。协议细节见上文「支持的 MCP 协议」 |
|
| 官方驱动,精确锁版本(非 semver,加 |
|
| schema 校验 |
开发依赖:typescript@^5.9.3(不用 7.x——那是 Go 重写的 tsgo)、@types/node@^22.19.1。
不引入 ORM:达梦没有 Prisma/Drizzle/Knex/MikroORM 方言,社区 fork(typeorm-dm、sequelize-dm8 等)周下载量仅个位数到两位数且基座老旧。更重要的是场景错配——ORM 的价值是实体映射,而 MCP 是运行时动态发现 schema,Entity 模型完全用不上。
测试用 Node 22 内置 node --test,不引 jest/vitest。
附录:字典视图真实列名
以下在真实 DM8 实例上实测所得,与 Oracle 文档有出入,勿照搬 Oracle 经验:
视图 | 关键列 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意不对称:索引位置列叫
COLUMN_POSITION,约束位置列叫POSITION。
SP_TABLEDEF(schema, table) 可用,返回 COLUMN_VALUE 列拼成的 DDL 文本。
目录结构
src/
├─ index.ts stdout 保护 + serveStdio + 退出清理
├─ server.ts createServer():建 McpServer 并按需注册工具
├─ config.ts 环境变量解析
├─ log.ts stderr-only 日志 + DDL/DML 审计
├─ db/
│ ├─ driver.ts 【唯一 import dmdb 的地方】CJS/ESM 互操作 + 真实语句类型码
│ ├─ connection.ts 懒加载/ping探活/毒化重连/mutex串行/大整数精确化重读
│ ├─ sql-guard.ts 五层门禁
│ ├─ identifiers.ts 标识符校验与引号
│ └─ types.ts
├─ tools/ register.ts(按开关注册)+ 每个工具一个文件
└─ format/ 序列化 / 三层截断 / markdown 渲染
scripts/ env.mjs(凭据校验)+ probe-connect / verify-dict / e2e-mcpLicense
Available Tools
9 toolsdm_describe_table查看表结构ARead-onlyIdempotent
返回一张表的完整结构:列定义(类型/长度/精度/可空/默认值)、主键、外键、唯一键、检查约束、索引及其包含的列、表注释与列注释,可选附带建表 DDL。写 SQL 之前调用它,避免猜列名和类型。注意:索引位置列在达梦里叫 COLUMN_POSITION,而约束位置列叫 POSITION,两者不同名。
Inputs: table (required), owner, include_ddl, response_format.
dm_explain查看 SQL 执行计划ARead-onlyIdempotent
返回一条 SELECT 语句在达梦 DM8 上的执行计划(走 EXPLAIN FOR,达梦的裸 EXPLAIN 不返回结果集)。输出包含 OPERATION、TAB_NAME、IDX_NAME、SCAN_TYPE、ROW_NUMS、COST 等列。排查慢查询、确认有没有走索引时调用。只接受 SELECT;EXPLAIN 不支持绑定参数,传入的 params 会被内联为字面量(经转义)。
Inputs: sql (required), params, response_format.
dm_list_schemas列出可访问的数据库模式ARead-onlyIdempotent
列出当前连接用户在达梦 DM8 中可访问的全部模式(schema/用户)。不确定某个表属于哪个 schema、或想确认库里有哪些业务库时调用。主查询走 ALL_USERS;若权限不足会退回 SYSOBJECTS 按 TYPE$='SCH' 查询。
Inputs: response_format. Returns: count, schemas
dm_list_tables列出达梦中的表ARead-onlyIdempotent
按模式名和表名关键字列出达梦 DM8 中的表,附带行数统计、所在表空间和表注释。用于"这个库里有哪些表""我要找订单相关的表"这类探索。注意 NUM_ROWS 来自统计信息,本库多数表未收集统计信息因而为 NULL;需要准确行数请用 dm_table_count 做精确 COUNT。标识符不区分大小写,传 order 或 ORDER 都可以。
Inputs: limit, owner, offset, pattern, +1 more.
dm_ping检查达梦连接与权限开关ARead-onlyIdempotent
检查到达梦 DM8 数据库的连接是否正常,返回服务端版本、实例名、当前连接用户,以及 DM_ALLOW_WRITE / DM_ALLOW_DDL 两个写权限开关的当前状态。排查"连不上"或"提示没有写权限"时先调用本工具。本工具只读取会话与实例元数据,不查询任何业务表。
Inputs: no named parameters. Returns: connected, startTime, ddlEnabled, currentUser, +4 more
dm_query执行只读 SELECT 查询ARead-onlyIdempotent
在达梦 DM8 上执行一条 SELECT 语句,返回列名与结果行。只放行 SELECT:INSERT/UPDATE/DELETE/DDL/多语句/存储过程调用都会被拒绝。分页请在 SQL 里写 LIMIT ? OFFSET ? 并把数值放进 params(DM8 原生支持绑定参数,已实测)。结果会自动按行数、单元格长度、总字符数三层截断,截断提示里会给出下一步建议。BIGINT 主键超出 JS 安全整数范围时会自动改用字符串重读,保证末几位不丢。
Inputs: sql (required), params, max_rows, timeout_ms, +1 more.
dm_search_objects按关键字搜索表和列ARead-onlyIdempotent
按关键字跨表搜索:表名、列名、列注释三处任一命中即返回,同时给出所属表、列类型和注释。适合"哪个表里有手机号字段""跟退款相关的列在哪"这类探索。中文注释也能搜(例如搜"订单")。
Inputs: keyword (required), limit, owner, offset, +1 more.
dm_table_count统计表行数ARead-onlyIdempotent
返回一张表的行数。默认执行精确 COUNT(*)。注意:达梦 ALL_TABLES.NUM_ROWS 来自统计信息,本库多数表未收集统计信息,该值通常为 NULL —— 所以不要拿 dm_list_tables 里的 NUM_ROWS 当真实行数,要用本工具。大表可以把 exact 设为 false,只读取统计估算值(可能不可用)。
Inputs: table (required), exact, owner, response_format. Returns: table, exactCount, lastAnalyzed, estimatedRows
dm_table_sample采样查看表数据ARead-onlyIdempotent
从指定表取几行样本数据,省去手写 SELECT 的步骤,也不用处理标识符大小写和引号。想快速了解一张表里"数据长什么样"时用这个;需要条件过滤或聚合请用 dm_query。默认只取 5 行,避免把上下文打满。
Inputs: table (required), limit, owner, offset, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Every tool has a clearly distinct role: ping for connectivity, list_schemas, list_tables, describe_table, query, sample, count, explain, and search_objects. Even the overlapping conveniences (sample/count vs query) are explicitly differentiated by purpose and usage guidance.
All tools share the dm_ prefix and use snake_case, but word order varies slightly: list_schemas/list_tables/describe_table/search_objects are action-first, while table_sample/table_count are object-first. The prefix makes the set predictable and readable despite the minor inconsistency.
Nine tools is well-scoped for a DM8 database exploration/query server. Each tool addresses a distinct operation without bloat, covering connection checks, metadata discovery, querying, sampling, counts, and execution plans.
For a read-only database toolset, the surface is complete: connection validation, schema/table discovery, detailed schema inspection, free-form SELECT, quick sampling, exact counts, EXPLAIN, and cross-object search. No obvious dead ends or missing operations within the stated domain.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a lightweight MySQL database interface via stdio, enabling query execution, data manipulation, schema inspection, and connection testing using FastMCP tools.3MIT
- AlicenseAqualityDmaintenanceProvides table structure browsing and read-only query capabilities for DM8 databases, enabling interaction through MCP clients like Claude Desktop.310ISC
- AlicenseNot gradedqualityBmaintenanceMulti-database management tool and MCP server supporting MySQL, PostgreSQL, SQLite, and Dameng DM8, enabling AI assistants to query and manage databases via stdio or HTTP.MIT
- -licenseNot gradedqualityNot gradedmaintenanceA multi-database MCP tool that enables LLM agents to securely query and write to databases via local stdio, supporting MySQL, Oracle, PostgreSQL, DM, SQLite and more.1-