DBHub 介绍(MCP 工具)

简介

DBHub 是 Bytebase 出品的极简、Token 高效的数据库 MCP Server,以只读方式连接 PostgreSQL、MySQL、MariaDB、SQL Server、SQLite,把数据库能力桥接给 AI 助手(Codex、Claude 等)。

整包只有两个工具:execute_sql 和 search_objects,设计目标就是让非技术用户也能安全地进行数据探查、报表和排障。

核心特点

• 两个工具走天下:execute_sql 执行查询,search_objects 浏览库内对象,Token 消耗低;
• 只读设计:SQL 分类器拒绝 UPDATE/DELETE/DDL 等写入语句,且数据库会话在引擎层面也被设为只读,双保险;
• 一条 DSN 接入:输入一条连接串即可连上数据库;
• Token 高效:工具说明精简,不问无关上下文。

支持数据库

• SSL 连接:在 DSN 后追加 ?sslmode=require
• 密码含特殊字符时需 URL 编码(如 $ → %24、^ → %5E、@ → %40)
• 建议使用最小权限的只读数据库账号

安装(基于官方 .mcpb 捆绑包,本机已验证)

要求:Node ≥ 22.5.0。官方发布 .mcpb 包已捆绑全部依赖,解压即可用,无需 npm install。

# 1. 下载官方 .mcpb 包(如 dbhub-1.2.1.mcpb)后解压
mkdir -p ~/.codex/mcp/dbhub
cd ~/.codex/mcp/dbhub
unzip ~/Downloads/dbhub-1.2.1.mcpb

# 2. 注册到 Codex(stdio + 环境变量 DSN)
codex mcp add dbhub \
  --env 'DBHUB_DSN=postgres://user:pass@host:5432/dbname' \
  -- node ~/.codex/mcp/dbhub/server/index.js \
       --transport stdio \
       --config ~/.codex/mcp/dbhub/dbhub.toml

也可在 macOS 的 ChatGPT/Codex 桌面应用中通过界面添加 MCP。

工具说明

execute_sql

对已连接数据库执行只读 SQL 查询(可选多个 ; 分隔语句)。

• 默认最大返回 1000 行,超限时结果带 truncated: true
• 写入语句会被分类器直接拒绝

search_objects

搜索和列出数据库对象(模式、表、列、索引、存储过程),支持渐进式详情:

• object_type: schema / table / view / column / procedure / function / index
• detail_level: names(仅名称)/ summary(摘要)/ full(完整详情)

使用示例

接入后,在 Codex 里直接用自然语言提问即可自动触发工具,例如:

「统计 Artist 表有多少行数据」→ 自动调用 execute_sql 执行 SELECT COUNT(*) FROM Artist

本机部署记录

• 安装位置:~/.codex/mcp/dbhub(版本 1.2.1)
• 已接入数据库:wzxy_dev(阿里云 RDS PostgreSQL 14.19,只读账号 coreuser)
• 验证结果:SELECT current_database() 返回 wzxy_dev;search_objects 正常列出 schema 与表
• 注册方式:codex mcp add 写入 ~/.codex/config.toml 的 [mcp_servers.dbhub]

参考链接

• GitHub 仓库:https://github.com/bytebase/dbhub
• 官网:https://dbhub.ai
• 官方安装文档:https://dbhub.ai/mcpb

注:DBHub 为 MIT 协议,由 Bytebase 维护。本文档基于 v1.2.1 实际安装验证整理,截至 2026-08-24。