DBHub MCP 接入实操：两个工具让 AI 安全查你的数据库

这篇教程带你把 DBHub 接进任意 MCP 客户端：不装数据库软件，先用它自带的示例库跑通「AI 查库」全流程，再换连你自己的 PostgreSQL 或 MySQL。全部步骤在一条命令行里完成，附上可复制的配置和实测中踩到的坑。

DBHub 是 Bytebase 开源的数据库 MCP 服务器，一个进程同时支持 PostgreSQL、MySQL、MariaDB、SQL Server、Oracle 和 SQLite。它在 GitHub 上有三千六百余星（以官方页面为准），并且是 Claude Code 官方文档里连接 PostgreSQL 的示例服务器。总纲入口在这里，产品档案见DBHub 页面。

为什么选它：默认只挂两个工具

多数数据库 MCP 服务器一上来就往上下文里塞几十个工具定义，长对话里挤占的窗口相当可观。DBHub 的思路相反——README 里给出了官方实测的对比：

数据引自 DBHub 官方 README 的 Token Efficiency 一节

剩下的两个内置工具 explain_sql（看执行计划）和 health_check（连接池状态）都是可选项，需要时在配置文件里显式打开。工具少不等于能力少——AI 拿到 execute_sql 就能跑任意 SQL，拿到 search_objects 就能自己摸清库结构，其余都交由模型组合完成。

DBHub 连接拓扑：MCP 客户端经 stdio/HTTP 接入，一个服务器对接六种数据库（依据官方文档绘制）

先过环境这道坎：Node 必须 22.5 以上

官方 npm 包 @bytebase/dbhub 当前版本 1.5.0，engines 字段写明 node >=22.5.0——因为它用了 Node 22 才内置的 node:sqlite 模块。这条不是吓唬人的：实测在一台 Node 20.16.0 的机器上运行安装命令，npm 只打出一个 EBADENGINE 警告，并不会拦你，真正的失败发生在启动连接 SQLite 那一刻：

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@bytebase/dbhub@1.5.0',
npm warn EBADENGINE   required: { node: '>=22.5.0' },
npm warn EBADENGINE   current: { node: 'v20.16.0', npm: '10.8.1' }
npm warn EBADENGINE }
...
Failed to connect to SQLite database: Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:sqlite
Fatal error: Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:sqlite

实测记录：Node 20 上警告不拦安装、启动才报错；换 Node 22 后同一命令全链路可用

不想升级系统 Node 的话有两个办法：用官方 Docker 镜像（自带兼容运行时，docker run --rm -p 8080:8080 bytebase/dbhub --transport http --port 8080 --demo），或者像这次实测一样，下载一个 Node 22 的独立压缩包解压到用户目录，只给这条命令用，不碰系统环境。确认版本用 node --version，输出 v22.x 才继续往下走。

五分钟跑通：demo 模式

DBHub 自带一个示例员工数据库，专门用来做无数据库环境的连通性验证。直接跑：

npx -y @bytebase/dbhub@latest --transport stdio --demo

stdio 是默认传输，客户端会把它作为子进程拉起，所以命令本身不会输出什么——它正等着 stdin 里的 JSON-RPC 消息。实测握手返回的 serverInfo 为 {"name": "DBHub MCP Server", "version": "1.5.0"}，随后 tools/list 恰好返回两个工具：execute_sql 和 search_objects，与 README 的主张完全一致。

真正要写进客户端的是下面这段配置。Claude Desktop、Cursor、Dify、LibreChat 等接受 mcpServers JSON 形态的客户端通用：

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub@latest", "--transport", "stdio", "--demo"]
    }
  }
}

保存后重启客户端，工具列表里出现 dbhub 即接入成功。想直观看到服务器状态，把 --transport stdio 换成 --transport http --port 8080，浏览器打开 http://localhost:8080/ 就是官方 Workbench 控制台，可以直接在网页上执行工具、查看请求记录。

换连你自己的数据库

把 --demo 换成 --dsn 即可。官方 Installation 页给的 PostgreSQL 示例：

npx -y @bytebase/dbhub@latest --transport http --port 8080 \
  --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

MySQL 写作 mysql://user:password@localhost:3306/dbname，SQLite 直接给文件路径 sqlite:///path/to/file.db。生产库建议加两道闸门（写在 TOML 配置里，见下节）：只读模式和行数上限。

两个工具怎么配合干活

接入后先让 AI 摸库，再让它查数，这是官方推荐的顺序。用 demo 库实测一遍完整过程，下面这张图把两步的因果关系放在一页里：

先 search_objects 摸结构、再 execute_sql 出结果：demo 库实测的完整提问路径（含反面教材）

第一步用 search_objects 看库里有什么。它的参数是 object_type（必填，枚举 schema/table/view/column/procedure/function/index）、pattern（LIKE 通配）和 detail_level（names/summary/full 三档，默认 names 最省 token）。传入 {"object_type": "table", "detail_level": "summary"}，demo 库的真实返回：

{"success": true, "data": {"object_type": "table", "count": 6, "results": [{"name": "department", "column_count": 2, "row_count": 9}, {"name": "dept_emp", "column_count": 4, "row_count": 1103}, {"name": "dept_manager", "column_count": 4, "row_count": 16}, {"name": "employee", "column_count": 6, "row_count": 1000}, {"name": "salary", "column_count": 4, "row_count": 9488}, {"name": "title", "column_count": 4, "row_count": 1470}], "truncated": false}}

第二步用 execute_sql 查数。比如问「薪水最高的三个人是谁」，AI 会基于上一步摸到的结构生成 JOIN 查询，实测返回：

{"success": true, "data": {"statements": [{"sql": "SELECT e.first_name, e.last_name, s.amount FROM employee e JOIN salary s ON e.emp_no = s.emp_no ORDER BY s.amount DESC LIMIT 3", "rows": [{"first_name": "Arno", "last_name": "Kumaresan", "amount": 136004}, {"first_name": "Arno", "last_name": "Kumaresan", "amount": 135407}, {"first_name": "Arno", "last_name": "Kumaresan", "amount": 131431}], "count": 3}]}}

顺带一个实测教训：第一次让 AI 查「top 5 employees by salary」（官方 Quickstart 的示例问法），它按直觉写了 FROM employees 和 s.salary，连续收到两条 EXECUTION_ERROR——demo 库的表名单数叫 employee，薪水列叫 amount 而不是 salary。这正是「先 search_objects 再 execute_sql」的价值：让模型先把真实表名列名摸清，命中率立刻回来了。

护栏：只读模式与行数上限

demo 模式默认可写——实测向 department 表 INSERT 一行，返回 {"success": true, "count": 1}，说明写操作畅通无阻。连生产库前先把这个口子关上。官方 Tools Overview 页给出的写法，在 dbhub.toml 里按工具粒度配置：

[[sources]]
id = "production"
dsn = "postgres://..."

[[tools]]
name = "execute_sql"
source = "production"
readonly = true    # 只允许 SELECT / SHOW / DESCRIBE / EXPLAIN
max_rows = 100     # 限制返回行数

[[tools]]
name = "search_objects"
source = "production"

启动时用 --config ./dbhub.toml 指定。注意官方文档的明确警告：--config 与 --dsn 互斥，TOML 里自己定义数据源，两者不能同时给。仓库根目录放了一份 dbhub.toml.example 可以照抄，多库连接、SSH 隧道、SSL 加密、自定义工具（把常用 SQL 封装成带参数的工具）都在这个文件体系里配置。给非技术同事开放查询时，常见做法是只留 search_objects、干脆不给 execute_sql——TOML 里为某个 source 只声明 search_objects 一条即可。

踩坑清单

除 Node 版本外，这四条是实测和官方文档里最容易撞上的：

1. search_objects 的类型参数叫 object_type，不叫 types。实测传 {"types": ["table"]} 收到校验错误，返回的枚举提示会把你纠正过来。2. demo 库表名是单数：employee、salary、department，问 AI 时别用 employees 这类复数，或者干脆先让它列表。3. HTTP 传输默认绑定 0.0.0.0，官方 Warning 原文提醒这会暴露在所有网络接口上——生产环境要么 --host 127.0.0.1 加反向代理，要么配 --auth-token 给每个请求加 Bearer 令牌。4. 桌面客户端找不到 npx 时（GUI 应用不继承终端 PATH），用 command -v npx 拿绝对路径替换配置里的 "command" 字段。

本文步骤、参数与配图依据 DBHub 官方文档（dbhub.ai 的 Installation、Quickstart、Command-Line Options、Tools Overview 各页）及 GitHub 仓库 README 整理，实测数据来自 1.5.0 版本的真实运行记录，版权归原作者所有。