@junjun-org/db-link-mcp

db-link-mcp

db-link-mcp 是一个面向数据库连接、工具编排和执行审计的 Node.js MCP Server。它把 MySQL、PostgreSQL、Redis、ClickHouse、SQLite 等数据源统一成 MCP 工具，供 Cursor、Codex 等 Agent 客户端调用。

它的重点不是“把数据库账号交给 Agent”这么简单，而是提供一套可管理、可分组、可审计的数据库工具工作台：

• 用管理端维护项目、数据源和工具，而不是手写大量 YAML。
• 按项目或环境暴露工具，例如测试库、生产只读库、监控诊断工具集。
• 对写操作记录 JSONL 审计、执行前快照和人工复核用回滚材料。
• 通过 execute_sql、只读 select_sql、配置化 SQL 工具和元数据工具，控制 Agent 能做什么。

快速开始

环境要求：

• Node.js >=22
• 当前机器能访问目标数据库

最快体验不需要提前准备配置文件：

npx -y @junjun-org/db-link-mcp

首次启动时，如果没有指定 --config 或 --prebuilt，服务会在应用主目录生成默认配置：

• Windows：C:\Users\<用户名>\.devops\db-link-mcp\db-link-mcp.yaml
• macOS：~/.devops/db-link-mcp/db-link-mcp.yaml
• Linux：~/.devops/db-link-mcp/db-link-mcp.yaml

默认配置包含一个禁用的 MySQL 占位数据源。补齐连接信息并启用后，工具才会真正注册给 MCP 客户端。

启动后会同时打开本地管理端，默认地址：

http://127.0.0.1:17321

需要指定自定义配置、只暴露某个项目、调整管理端端口或关闭管理端时，可追加 --config、--project、--web-port、--no-web 等参数。默认使用自动生成的配置文件即可。

也可以全局安装后直接运行：

npm install -g @junjun-org/db-link-mcp
db-link-mcp

MCP 客户端配置

Cursor：

{
  "mcpServers": {
    "db-link-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@junjun-org/db-link-mcp"
      ]
    }
  }
}

Codex：

[mcp_servers.db-link-mcp]
command = "npx"
args = ["-y", "@junjun-org/db-link-mcp"]

默认会使用自动生成的配置文件，并注册全部启用工具。需要固定配置文件或只暴露某个项目时，再在 args 中追加 --config 或 --project。

管理端工作台

管理端是 db-link-mcp 的核心入口。它会读取当前生效 YAML，并把项目、数据源、工具和审计记录组织成一个可操作的浏览器工作台。

数据源与项目管理

• 左侧按项目展示数据源树，可新建、编辑、删除项目。
• 支持 MySQL、PostgreSQL、SQLite、Redis、ClickHouse 数据源。
• 可通过右键菜单或详情页新增、编辑、删除、启用、停用数据源。
• 数据源详情展示名称、描述、类型、主机、端口、数据库和启用状态。
• 新建或编辑数据源时可以测试连接，减少 YAML 写错后才发现的问题。
• 左侧数据源面板支持拖动调宽，便于在多项目、多连接场景下查看长名称。

所有管理端变更都会写回当前配置文件。配置保存后会通知 MCP 客户端刷新工具列表；如果客户端暂时没刷新出新工具，可以用内置兜底工具 call_configured_tool 调用当前配置中已存在的工具。

工具配置

每个数据源下面可以配置多个工具。工具决定 Agent 能调用什么，而不是简单地把整个数据库连接暴露出去。

• 工具列表展示工具名、启用状态、类型、描述，并支持新增、编辑、删除、启用、停用。
• MySQL、PostgreSQL、SQLite 支持 execute_sql 和只读 select_sql。
• MySQL、PostgreSQL 支持表结构、执行计划、活跃查询、锁、统计、膨胀表等诊断类工具。
• ClickHouse 支持执行 SQL、列数据库、列表。
• Redis 支持配置化命令工具。
• SQL 模板工具支持参数占位，适合把常用查询或受控写入封装成稳定 Data API。

管理端会根据数据源类型生成默认工具名和工具类型。生产类数据源建议使用更窄的工具面：启用 select_sql 和配置化 Data API，谨慎开放 execute_sql。

开发模式与生产模式

SQL 数据源支持访问模式切换：

• 开发模式：展示并启用 execute_sql，适合开发、联调、临时排查。
• 生产模式：隐藏或停用 execute_sql；查询走 select_sql，写操作走配置化 Data API。

同一个数据源上不能同时启用 execute_sql 和 Data API 写工具。这个限制是为了避免 Agent 同时拥有“任意 SQL 写入”和“受控写入接口”，导致权限边界不清。

执行审计与回滚工作台

审计能力是 db-link-mcp 的重点能力。它记录的不只是“谁调了工具”，还会尽量保存写操作的执行前材料，方便事后追溯和人工复核。

审计页面

管理端的“执行审计”页提供一个会话化工作台：

• 按日期、数据源、操作人、会话 ID 查询审计记录。
• 左侧展示会话汇总，包括执行次数、可回滚数量、操作人和坏行统计。
• 右侧展示选中会话的执行记录，包括时间、数据源、操作类型、状态、调用 ID、回滚状态。
• 详情弹窗展示 SQL 原文、执行前数据、执行结果和回滚 SQL。
• 对带有回滚 SQL 的记录，支持单条回滚，也支持按会话倒序执行可回滚记录。

页面只展示变更审计，也就是写操作相关记录。普通调用流水仍会写入 JSONL 文件，便于离线排查。

审计文件

日志写入当前配置文件所在目录的 logs/ 子目录，并按本地日期切分：

logs/calls/db-link-mcp-audit-YYYYMMDD.jsonl
logs/changes/db-link-mcp-change-audit-YYYYMMDD.jsonl
logs/rollbacks/db-link-mcp-rollback-YYYYMMDD.jsonl

默认配置文件位于 ~/.devops/db-link-mcp/db-link-mcp.yaml 时，日志示例：

~/.devops/db-link-mcp/logs/calls/db-link-mcp-audit-20260618.jsonl
~/.devops/db-link-mcp/logs/changes/db-link-mcp-change-audit-20260618.jsonl
~/.devops/db-link-mcp/logs/rollbacks/db-link-mcp-rollback-20260618.jsonl

STC_HOME 可以改变默认应用主目录；显式传入 --config 时，日志跟随配置文件父目录。

写操作审计上下文

非 SELECT 写操作必须提供操作人：

• senderId：必填，表示操作人或发起方。
• sender_id：兼容别名。
• agentName：可选，用于辅助识别调用来源。

sessionId 由服务端决定。Codex 会优先使用 x-codex-turn-metadata.session_id/sessionId；其他客户端或取不到 metadata 时，会使用当前 db-link-mcp 进程启动时生成的 UUID。Agent 不需要也不应该手动传 sessionId。

写操作缺少 senderId / sender_id 时会被拒绝执行。审计日志本身不阻断成功写入后的记录落盘，但回滚材料生成失败时会在记录中写明原因。

回滚材料边界

回滚生成是保守的辅助能力，不是通用 SQL 回滚引擎。

目前支持的自动回滚材料主要包括：

• MySQL、PostgreSQL、SQLite 的简单单表 UPDATE、DELETE、INSERT。
• MySQL、PostgreSQL、SQLite 的简单 CREATE TABLE。
• 简单列级 ALTER TABLE，例如 ADD COLUMN、DROP COLUMN、MySQL MODIFY/CHANGE COLUMN、PostgreSQL ALTER COLUMN TYPE/DEFAULT/NOT NULL、SQLite RENAME COLUMN。
• Redis 在能识别 key 且数据源支持快照时，可在审计记录中生成对应恢复命令。

以下场景会保留审计记录，但标记为不可自动生成回滚材料：

• 多语句、复杂 SQL、多表 DML、无法解析目标表。
• 无法在执行前拿到足够快照。
• 无法用主键或确定条件精准定位原 SQL 影响的同一批行。
• 无 WHERE 的高风险写操作。
• 复杂 DDL、索引/外键/约束/触发器/生成列依赖等列外对象变更。
• ClickHouse 写操作。

生成的回滚 SQL / 命令定位为人工复核材料。系统不会把它声明为事务级恢复保证；执行前请确认目标库、影响行和执行顺序。当前管理端的回滚执行按钮面向 SQL 回滚 SQL，Redis 恢复命令会作为审计材料保留。

YAML 配置格式

管理端会维护这份 YAML；也可以手写。配置文件使用项目优先的单文档 YAML：顶层是项目名，项目下面声明数据源，数据源下面声明工具。

"<project-name>":
  description: "<project-description>"
  sources:
    "<source-name>":
      description: "<source-description>"
      type: mysql
      enabled: true
      host: ${DB_HOST}
      port: ${DB_PORT}
      database: ${DB_NAME}
      user: ${DB_USER}
      password: ${DB_PASSWORD}
      queryTimeout: 30s
      tools:
        "<select-tool-name>":
          type: mysql-select-sql
          description: "<select-tool-description>"
        "<list-tables-tool-name>":
          type: mysql-list-tables
          description: "<metadata-tool-description>"
        "<execute-tool-name>":
          type: mysql-execute-sql
          enabled: false
          description: "<execute-tool-description>"

项目是工具分组，例如 <project-dev>、<project-prod>。配置加载时会自动展开成运行时结构，项目优先格式下 tool.source 不需要手写，会自动指向它所在的数据源。

不指定 --project 时会注册全部工具，因此数据源名和工具名需要在整个配置文件内唯一。建议工具名带上项目或环境前缀，例如 <project>_<purpose>_select_sql，避免不同项目之间重名。

如果 project 没有显式写 tools，默认暴露该 project 下 sources 定义的全部工具。如果一个 project 只是复用其他 project 已定义的工具，可以只写 tools：

"<data-project-name>":
  description: "<data-project-description>"
  sources:
    "<source-name>":
      description: "<source-description>"
      type: mysql
      host: ${DB_HOST}
      tools:
        "<execute-tool-name>":
          type: mysql-execute-sql
        "<query-plan-tool-name>":
          type: mysql-get-query-plan

"<monitor-project-name>":
  description: "<monitor-project-description>"
  tools:
    - "<query-plan-tool-name>"

"<all-tools-project-name>":
  description: "<all-tools-project-description>"
  tools: "*"

tools: "*" 表示引用配置里的全部工具。工具暴露给 Agent 时会保留自身 description，并自动追加数据源和 project 信息：

<tool-description>

数据源：<source-name>
数据源说明：<source-description>
数据库类型：mysql
数据库：<database-name>

项目：<project-name>
项目说明：<project-description>

支持环境变量：

• ${ENV}
• ${ENV:default}

也支持通过 enabled 控制是否启用：

enabled: ${DB_ENABLED:false}

被禁用的 source 不会创建连接，引用它的 tool 也不会注册。被禁用的 tool 会保留在配置中，但不会暴露给 MCP 客户端。

常见工具类型

• MySQL：execute_sql、select_sql、list_tables、get_query_plan、list_active_queries、list_table_stats、list_tables_missing_unique_indexes、list_table_fragmentation
• PostgreSQL：execute_sql、select_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_procedure、get_query_plan、list_active_queries、long_running_transactions、list_locks、replication_stats、database_overview、list_query_stats、list_table_stats、list_pg_settings、list_top_bloated_tables
• Redis：配置化 commands
• ClickHouse：execute_sql、list_databases、list_tables
• SQLite：execute_sql、select_sql、list_tables

execute_sql 默认不做只读限制，是否允许 DML / DDL 由数据库账号权限决定。select_sql 只允许 SELECT / WITH / SHOW / DESCRIBE / EXPLAIN 等查询语句，适合生产只读查询场景。

本地敏感字段加密

配置中的密码可以使用字段级密文，避免 YAML 中直接保存明文：

npx -y @junjun-org/db-link-mcp encrypt-secret \
  --config /绝对路径/db-link-mcp.yaml \
  --field '<project-name>.sources.<source-name>.password' \
  --value '<数据库密码>'

命令会在本机用户目录下自动生成随机 root key，并输出类似下面的密文：

enc:v1:local:default:...

把输出值写回对应字段即可：

"<project-name>":
  sources:
    "<source-name>":
      type: mysql
      host: ${DB_HOST}
      database: ${DB_NAME}
      user: ${DB_USER}
      password: enc:v1:local:default:...
      tools:
        "<select-tool-name>":
          type: mysql-select-sql

后续正常启动时会自动解密：

npx -y @junjun-org/db-link-mcp

默认本地 key 目录：

• Windows：C:\Users\<用户名>\.devops\db-link-mcp\keys
• macOS：~/.devops/db-link-mcp/keys
• Linux：~/.devops/db-link-mcp/keys

如需统一指定应用主目录，可以设置 STC_HOME，key 会放在 ${STC_HOME}/keys 下。

默认模式使用每个用户本机随机 key 文件，文件权限会尽量限制为当前用户可读。它主要防止配置文件误提交、被搜索或被直接打开时暴露明文；如果配置密文和本地 key 文件同时泄露，或同一系统用户下有恶意程序读取 key 文件，仍然可以解密。

内置模板

如需查看完整多数据库示例，可以临时使用内置模板：

npx -y @junjun-org/db-link-mcp --prebuilt local

--prebuilt local 主要用于演示和调试，不是常规启动必需参数。生产使用建议维护自己的配置文件，并通过管理端持续更新。

本地开发

源码启动：

node src/server.js --config ./db-link-mcp.yaml

运行测试：

npm test

构建 Web 管理端：

npm run build:web

预览 npm 发布包内容：

npm pack --dry-run

发布到 npm：

npm publish --access public