db-tanxii-mcp

一个用于 Claude Code 的数据库 MCP Server（stdio），让 Claude 通过工具方式安全访问数据库。

它能做什么

• 支持多连接，按连接名管理连接池
• 支持多数据库：MySQL / OceanBase MySQL / Oracle / OceanBase Oracle / Postgres / Pgoracle / SQL Server / 达梦
• 支持库表/视图/例程探索、统一对象详情查看、列清单查看、索引查看、DDL 获取、预览查询、只读查询、执行计划、对象搜索、结构比对、MySQL 到 Oracle-like 的 SQL 翻译
• 内置安全边界：写操作必须走 execute

文档怎么读

• 想部署、注册、排查运行问题：看本 README
• 想看仓库内协作约束：看 CLAUDE.md
• 想看完整工具手册：看 工具.md

目录

• 30 秒上手
• 快速开始
• 配置
• 推荐使用方式
  • 常见意图 → 推荐工具
  • 一条典型探索路径
• 结构比对能力
• SQL 翻译能力
• 会话与上下文规则
• 运行与部署
  • 热更新
  • 运行时排障
• 达梦兼容模式
• Oracle 11g / Thick 模式
• 安全说明
• 卸载
• 常见问题
• 参考

30 秒上手

如果你只是想先把它跑起来，最短路径是：

1. 全局安装：npm install -g db-tanxii-mcp
2. 准备 Windows 配置文件：%APPDATA%/db-tanxii-mcp/.env.production
3. 注册到 Claude Code：claude mcp add db-tanxii-mcp --scope user -- db-tanxii-mcp
4. 验证注册：claude mcp list

示例配置：

DB_DEFAULT_CONNECTION=MYSQL
DB_URL__MYSQL=mysql://<user>:<password>@<host>:<port>/<database>

如果你接下来想真正开始看库表，继续看下方“快速开始”“推荐使用方式”和 工具.md 即可。

快速开始

1. 全局安装

npm install -g db-tanxii-mcp

安装后可用命令：

• db-tanxii-mcp

2. 准备配置文件（Windows 默认）

默认读取：%APPDATA%/db-tanxii-mcp/.env.production

你需要创建该文件，并写入数据库连接配置。示例见下文“配置示例”。

3. 启动 MCP Server

安装后的 CLI 命令为 db-tanxii-mcp，对应 npm 包的 bin 入口。

db-tanxii-mcp

该进程通过 stdio 与 Claude Code 通信，通常由 Claude Code / MCP 管理器拉起；在包内实际会进入 dist/app/cli.js，再加载运行中的 MCP Server。

4. 在 Claude Code 中注册

claude mcp add db-tanxii-mcp --scope user -- db-tanxii-mcp

验证：

claude mcp list

配置

配置项

通过 dotenv / 环境变量配置多连接 URL：

• 默认连接名：DB_DEFAULT_CONNECTION=<name>
• 每个连接 URL：DB_URL__<name>=<url>

配置示例

DB_DEFAULT_CONNECTION=MYSQL

# mysql://<user>:<password>@<host>:<port>/<database>
DB_URL__MYSQL=mysql://<user>:<password>@<host>:<port>/<database>

# Oracle
# oracle://<user>:<password>@<host>:<port>/<service_name>
# 若未显式设置 schema，会默认使用 URL 中的 <user> 作为当前 session schema
DB_URL__ORACLE=oracle://<user>:<password>@<host>:<port>/<service_name>

# Pgoracle
# pgoracle://<user>:<password>@<host>:<port>/<database>
DB_URL__PGORACLE=pgoracle://<user>:<password>@<host>:<port>/<database>

# Postgres
# postgres://<user>:<password>@<host>:<port>/<database>
DB_URL__POSTGRES=postgres://<user>:<password>@<host>:<port>/<database>

# SQL Server
# sqlserver://<user>:<password>@<host>:<port>/<database>
# 注意：URL 中的 <database> 固定为连接数据库；工具参数里的 schema 表示 SQL Server schema（如 dbo）
DB_URL__SQLSERVER=sqlserver://<user>:<password>@<host>:<port>/<database>

# 达梦
# 支持 dameng:// 或 dm://
# dameng://<user>:<password>@<host>:<port>/<database>
DB_URL__DAMENG=dameng://<user>:<password>@<host>:<port>/<database>

# OB-MySQL
# obmysql://<user>:<password>@<host>:<port>/<database>
DB_URL__OBMYSQL=obmysql://<user>:<password>@<host>:<port>/<database>

# Oracle Instant Client 目录（可选，用于 Thick 模式；Oracle 11g 推荐）
ORACLE_CLI_HOME=D:/Software/instantclient/instantclient_23_0

更多示例见：.env.example

不同数据库的 schema 语义

• MySQL / OB-MySQL / Dameng：默认 schema = URL 中的 database
• Oracle：默认 schema = URL 中的 user
• SQL Server：默认不设置 session schema；URL 中的 database 是连接数据库，不是 schema。如需按 schema 工作，请显式传 schema 或先执行 use_schema
• Postgres / Pgoracle / OB-Oracle：默认不设置 session schema

推荐使用方式

如果你是通过 Claude Code 使用这个 MCP，推荐先做“上下文确认 → 元数据探索 → 小样本预览 → 正式查询”，而不是一上来就写 SQL：

1. list_connections
2. use_connection
3. current_context
4. list_schemas
5. use_schema
6. list_tables
7. list_views / list_routines
8. describe_object / describe_table / list_columns
9. preview_table / preview_query
10. readonly_query

原则：

• 普通只读查询优先 readonly_query
• 只有需要 SHOW / DESCRIBE / EXPLAIN 时才使用 query
• 写操作只能使用 execute
• 结构化执行存储过程/函数时优先使用 execute_routine
• MySQL / OB-MySQL 的 execute 支持 delimiter 脚本解析，也支持受限的 @file.sql / source file.sql 服务端本地脚本引用

常见意图 → 推荐工具

| 你想做什么 | 推荐工具 | |---|---| | 确认连接与上下文 | list_connections / use_connection / current_context | | 浏览 schema 与对象 | list_schemas / list_tables / list_views / list_routines | | 查看表与对象详情 | describe_object / describe_table / list_columns / list_indexes | | 查看定义 | describe_object_full / get_ddl_full | | 预览数据或试跑查询 | preview_table / preview_query | | 执行只读查询 | readonly_query | | 执行 SHOW / DESCRIBE / EXPLAIN | query / explain_query | | 搜索对象 | search_objects | | 修改数据 | execute | | 结构化调用存储过程 / 函数 | execute_routine | | 执行 MySQL DDL / 过程定义脚本 | execute | | 做结构比对 | search_similar_tables / compare_schema / compare_table | | 对比对结果做总结 | assess_similar_table / assess_schema_diff / assess_table_diff | | 排查连接与运行时状态 | health / runtime_config_status / reset_connection_session |

完整工具说明见：工具.md

一条典型探索路径

第一次接入数据库时，可直接走这条最短链路：

list_connections → use_connection → current_context → list_schemas → use_schema → list_tables → describe_table → preview_table → readonly_query

需要继续下钻时，再按需补 list_views、list_indexes、describe_object_full、get_ddl_full。

结构比对能力

除了常规查询，本项目还支持跨连接、跨数据库类型的结构核对：

• search_similar_tables：先找候选对应表
• compare_schema：做 schema 级范围对比
• compare_table：做单表列级精确对比

推荐链路：

1. 先用 search_similar_tables 找候选表
2. 再用 compare_schema 做范围级结构核对
3. 最后用 compare_table 钻取单表列级差异

结构评估与总结能力

当原始结果较多、你更关心“重点结论”时，可以继续使用评估类工具：

• assess_similar_table：对相似表候选结果做进一步收敛
• assess_schema_diff：对 schema 级差异做摘要化总结
• assess_table_diff：对单表列级差异做摘要化总结

推荐用法：

1. 先用探索/比对工具拿到原始结果
2. 再用 assess_* 工具压缩成更适合阅读和决策的结论
3. 如需完整细节，再回到原始工具结果继续下钻

MySQL 脚本执行能力

除了普通 DML，本项目当前的 execute 还支持 MySQL / OB-MySQL 的脚本内容执行，适合处理这类带 delimiter 的建表、改表、存储过程定义脚本，也支持受限的 @alter_table.ddl.sql / source alter_table.ddl.sql 这类服务端本地脚本引用输入。

适用范围：

• 通过 execute.sql 直接传入脚本内容
• 支持 delimiter $$ / delimiter ;
• 支持 create procedure ... begin ... end、call ...、create table ...、alter table ... 等常见脚本片段
• 支持受限的 @file.sql / source file.sql 服务端本地脚本引用
• 解析时会保护字符串、注释、反引号标识符中的分号，不会再按 ; 粗暴拆分

安全边界：

• @file.sql / source file.sql 仅允许当前工作目录内的相对 .sql / .ddl.sql 文件，不支持绝对路径、盘符路径、URL、.. 越级路径
• MySQL DDL 可能触发隐式提交，即使传了 transaction=true 也不应视为整段脚本绝对原子

推荐用法：

1. 先确认连接已经切到 MySQL / OB-MySQL
2. 可直接把 .sql 文件内容整体传给 execute.sql，也可传 @alter_table.ddl.sql 或 source alter_table.ddl.sql

Oracle / 达梦 / Pgoracle 脚本引用执行能力

对 Oracle / OB-Oracle / 达梦 / Pgoracle 连接，execute 还支持受限的服务端本地脚本引用语义，适合处理这类 @alter_table.ddl.sql 或 start alter_table.ddl.sql 输入。

适用范围：

• 仅当 execute.sql 整体就是单个脚本引用语句时生效
• 当前支持 @file.sql、start file.sql
• 服务端会先读取当前工作目录中的 .sql / .ddl.sql 文件，再按现有多语句执行链路继续执行

安全边界：

• 不支持 @@file.sql
• 不支持绝对路径、盘符路径、URL、.. 越级路径
• 仅允许当前工作目录内的相对 .sql / .ddl.sql 文件

推荐用法：

1. 先确认连接已经切到 Oracle / OB-Oracle / 达梦 / Pgoracle
2. 传入 @alter_table.ddl.sql 或 start alter_table.ddl.sql
3. 对高影响脚本先在测试环境验证，再在正式环境执行

SQL 翻译能力

除了查询、执行计划与结构比对，本项目还提供了一个独立的 SQL 翻译工具：translate_sql。

适用范围：

• 源方言固定为 mysql
• 目标方言支持：oracle、dameng、tdsql-oracle
• 首版覆盖：SELECT / INSERT / UPDATE / DELETE
• 翻译在 MCP 服务端内以规则方式完成，不调用大模型

当前已支持的高频改写包括：

• LIMIT → Oracle-like 分页写法
• IFNULL(x, y) → NVL(x, y)
• IF(cond, a, b) → CASE WHEN ... THEN ... ELSE ... END
• CONCAT(a, b, ...) → a || b || ...
• NOW() → SYSDATE
• 必要时补 FROM DUAL
• MySQL 反引号标识符去除

风险边界：

• INSERT ... ON DUPLICATE KEY UPDATE：会标记高风险并要求人工复核
• REPLACE INTO：会标记为不支持自动等价翻译并要求人工复核

返回结果会统一包含：

• translatedSql
• executableConfidence
• warnings
• unsupported
• manualReviewRequired
• appliedRules

推荐用法：

1. 先用 translate_sql 把常见 MySQL SQL 改写到目标 Oracle-like 方言
2. 再结合目标数据库的 preview_query / readonly_query / explain_query 做验证
3. 对带 manualReviewRequired=true 的结果必须人工复核后再执行

会话与上下文规则

MCP 会话内会维护两个状态：

• 当前连接（current connection）
• 当前 schema（current schema）

连接解析优先级：

1. 本次工具调用显式传入的 connection / schema
2. 当前会话已选中的 connection / schema
3. 环境默认连接 DB_DEFAULT_CONNECTION

补充规则：

• 显式传入 connection 时，会更新当前会话 connection
• 切换 connection 且未同时提供新 schema 时，旧 schema 失效
• 显式设置 schema（如 use_schema，或 schema + rememberSchema=true）后，会话会记住该 schema
• 新开 Claude 会话或重启 MCP 进程后，会话级 connection/schema 会丢失

运行与部署

Windows 默认配置位置

• 配置目录：%APPDATA%/db-tanxii-mcp/
• 配置文件：%APPDATA%/db-tanxii-mcp/.env.production

CLI 启动时会将 NODE_ENV 设为 production，并读取该路径下的配置文件。

热更新

运行中的 MCP 进程会监听：

• %APPDATA%/db-tanxii-mcp/.env.production

当该文件变化时：

• 自动重新加载运行时配置
• 后续请求尽快使用最新配置
• 对于配置发生变化的连接池，会按连接名安全切换到新 pool
• 已在执行中的请求尽量继续使用旧连接直到完成

适合热更新的配置：

• DB_DEFAULT_CONNECTION
• DB_URL__<name>
• URL 中依赖的普通占位符变量

需要重启后生效的配置：

• ORACLE_CLI_HOME
• 其他影响原生驱动初始化方式的变量

运行时排障

推荐顺序：

• 上下文确认：current_context → connection_status
• 连通性确认：health
• 热更新 / pool / 配置排查：runtime_config_status
• 会话重置：reset_connection_session

达梦兼容模式

如果达梦连接时遇到类似错误：

• [6071] 消息加密失败
• error:0308010C:digital envelope routines::unsupported

通常是 dmdb 驱动在当前 Node / OpenSSL 环境下需要 legacy cipher，而 Node 22 + OpenSSL 3 默认未启用。

此时建议在 Claude Code 注册 MCP 时显式开启兼容模式。

Windows 推荐方式

仓库根目录提供了两个脚本：

• reset-db-tanxii-mcp.ps1
• reset-db-tanxii-mcp.bat

它们会自动完成：

1. 卸载当前全局安装的 db-tanxii-mcp
2. 从当前仓库重新全局安装
3. 移除旧的 Claude MCP 配置
4. 重新注册 db-tanxii-mcp，并通过 NODE_OPTIONS=--openssl-legacy-provider 开启兼容模式

使用方式：

.\reset-db-tanxii-mcp.ps1

如遇 PowerShell 执行策略限制：

powershell -ExecutionPolicy Bypass -File .\reset-db-tanxii-mcp.ps1

或使用批处理：

.\reset-db-tanxii-mcp.bat

手动注册（Windows）

优先推荐直接注册全局命令：

claude mcp remove db-tanxii-mcp
npm uninstall -g db-tanxii-mcp
npm install -g db-tanxii-mcp
claude mcp add --scope user --env=NODE_OPTIONS=--openssl-legacy-provider db-tanxii-mcp -- db-tanxii-mcp

如果你确实需要显式指定 Node 与入口文件，也应指向当前包的 CLI 入口 dist/app/cli.js：

claude mcp add --scope user --env=NODE_OPTIONS=--openssl-legacy-provider db-tanxii-mcp -- C:\nvm4w\nodejs\node.exe C:\nvm4w\nodejs\node_modules\db-tanxii-mcp\dist\app\cli.js

如果你使用本地构建产物调试：

claude mcp remove db-tanxii-mcp-dev
claude mcp add db-tanxii-mcp-dev --scope user -e NODE_OPTIONS=--openssl-legacy-provider -- node F:/code/tanxii/db-tanxii-mcp/dist/app/cli.js

Oracle 11g / Thick 模式

当 Oracle 版本较老时，oracledb Thin 模式可能报：

• NJS-138: connections to this database server version are not supported by node-oracledb in Thin mode

解决方式：启用 Thick 模式（OCI）。

Windows 示例

1. 安装 Oracle Instant Client，例如：C:\oracle\instantclient_19_24
2. 设置环境变量：

setx ORACLE_CLI_HOME "C:\oracle\instantclient_19_24"
setx PATH "$env:PATH;C:\oracle\instantclient_19_24"

3. 重启运行环境后，再启动 db-tanxii-mcp

安全说明

工具层安全边界

• readonly_query：仅允许 SELECT
• query：仅允许 SELECT / SHOW / DESCRIBE / EXPLAIN
• execute：用于写操作，如 INSERT / UPDATE / DELETE
• execute_routine：用于结构化调用存储过程 / 函数，支持 routineType、参数方向、返回值与结果集的统一输出

是否允许 DROP、TRUNCATE 等高风险语句，取决于当前版本实现与数据库账号权限配置；仅依赖工具层限制并不可靠。

生产建议

• 生产库默认只配置只读连接
• 如必须写入，单独配置写连接并明确标注连接名
• 不建议将拥有 DDL 权限的账号配置给该工具服务
• 使用最小权限账号，并确保网络、白名单、防火墙策略正确

卸载

如果你要移除当前 MCP，建议按下面顺序：

1. 移除 Claude Code 中的 MCP 注册：

claude mcp remove db-tanxii-mcp --scope user

2. 检查是否仍有残留：

claude mcp list

3. 卸载全局 npm 包：

npm uninstall -g db-tanxii-mcp

4. 检查全局包是否还存在：

npm list -g --depth=0 db-tanxii-mcp

5. 按需清理本地配置目录（Windows）：

• %APPDATA%/db-tanxii-mcp/
• %APPDATA%/db-tanxii-mcp/.env.production

常见问题

Claude Code 里看不到 MCP Server

先检查：

claude mcp list

确认注册命令是否正确：

claude mcp add db-tanxii-mcp --scope user -- db-tanxii-mcp

连接失败 / 超时

建议依次排查：

• 数据库网络是否连通
• URL、用户名、密码是否正确
• 当前 connection/schema 是否符合预期
• Oracle 11g 是否需要 Thick 模式
• 达梦在当前 Node / OpenSSL 环境下是否需要兼容模式

参考

• 示例配置：.env.example
• 工具手册：工具.md
• 仓库协作指南：CLAUDE.md
• npm 脚本定义：package.json
• 应用入口与工具注册：src/app/index.ts
• CLI 启动与热更新入口：src/app/cli.ts