Universal DB (read-only)

universal-db-mcp

快速开始 · 工具 · 安全模型 · 离线安装 · 文档 · 项目主页 · 报告漏洞

让 AI Agent 安全地只读访问你的数据库。 universal-db-mcp 是一个 MCP 服务，允许 Claude Code、Cursor、VS Code 或任何 MCP 客户端发现、记录、分析、搜索和查询你声明的数据库，仅限这些数据库。每条语句在执行前都会经过解析，并且必须是单条只读语句；服务在只读会话中运行，会屏蔽看似敏感的列，并审计每次调用。写入操作会被拒绝，而非仅仅被劝阻。服务绝不会调用大模型，不发送遥测数据，也不会在运行时安装任何内容，因此即使在完全无法访问互联网的网络中也能运行。

状态： 已通过生产环境安全审查和三轮后续代码审查进行加固（2026-09/10）。IMPLEMENTATION_STATUS.md 如实记录了已实现的内容、验证情况及验证方式，以及仍未解决的问题；本文中的声明仅限于其门禁和 test-evidence/ 所证明的内容。

功能

引擎（下表中的每个版本都通过了版本矩阵测试， scripts/version_matrix/，结果位于 test-evidence/version-matrix/）：

引擎	已验证版本
PostgreSQL	12、13、14、15、16、17
MySQL / MariaDB	MySQL 5.7、8.0、8.4；MariaDB 10.6、11.4
ClickHouse	23.8、24.3、24.8、25.3
Oracle	18c、21c、23（thin 模式）；11g、18c、23（thick 模式，用于旧版密码验证器）
SQL Server	2017、2019、2022
Db2	11.5.8、11.5.9
SQLite	CPython 构建所使用的 SQLite

29 个工具（docs/tools.md 是规范）：

• 连接： db_list_connections、db_test_connection、db_get_capabilities。
• 目录： db_list_catalogs、db_list_databases、db_list_schemas、 db_list_tables、db_get_table、db_list_columns、db_list_views、 db_list_synonyms、db_list_routines、db_list_indexes、 db_get_relationships、db_get_statistics、db_search_metadata、 db_get_catalog。
• 读取数据： db_validate_query、db_query、db_sample_table、 db_explain（仅执行计划，不执行查询）、db_get_query_history。
• 发现、审查和文档编写： db_profile_table、 db_search_values（无需编写 SQL，即可跨表和连接查找值）、 db_infer_relationships、db_review_schema（按优先级排列的优化发现）、 db_document_schema（Markdown 数据字典）。
• 联邦读取： db_federated_query（执行一条语句，或每个连接执行一条语句，然后合并结果）和 db_federated_join（跨两个连接执行有界哈希连接）。

它如何保障数据库安全

纵深防御；详情和限制请参阅 docs/security.md 和 docs/session-safety.md。

1. 数据库登录凭据是首要控制措施。 为每个连接创建一个仅限 SELECT 的登录账号，并将其权限限制在 allowed_schemas 中列出的架构。唯一的例外是 Db2 的 db_explain：它会将计划行写入 DBA 预先创建的解释表，读回这些行并将其删除；该登录账号也需要对这些表拥有 INSERT、SELECT 和 DELETE 权限，且权限仅限于这些表（Oracle 的计划会写入会话私有的 PLAN_TABLE，无需授权）。列级授权或视图才是保护敏感列的真正手段。
2. 只读会话。 默认启用，并由服务器自身在 PostgreSQL、MySQL/MariaDB、ClickHouse 和 SQLite 上强制执行；Db2 使用 UR，SQL Server 使用 READ UNCOMMITTED，因此读取不会获取共享锁。不存在写入模式：配置加载时会拒绝 security.read_only: false、allow_write_operations: true 和连接中的 read_only: false。每个会话还会固定使用决定服务器如何解析语句的设置（MySQL sql_mode、PostgreSQL standard_conforming_strings、SQL Server QUOTED_IDENTIFIER 等），确保服务器读取的内容与防护机制解析的内容完全一致。
3. SQL 防护机制会按照连接所用的方言解析每条语句，并且只接受一条读取语句；无法解析的内容一律拒绝。在 allowed_schemas 非空时，每个表都必须使用架构限定名（SELECT * FROM ocean.buoys，而非 SELECT * FROM buoys），因为否则由数据库引擎决定使用哪个架构。在 Oracle、Db2 和 PostgreSQL 上，CTE 名称和未加引号的表名必须为 ASCII。无论 allowed_system_schemas 开放哪些架构，都会拒绝显示其他会话 SQL、列统计信息或存储凭据的视图；Oracle 的 SYS.DUAL 和 Db2 的 SYSIBM.SYSDUMMY1 至 SYSIBM.SYSDUMMY4 始终可读。绑定参数会原样传递给驱动程序，并且经过验证。
4. 无法证明安全时就拒绝的脱敏机制。 匹配敏感模式的列（内置模式及 security.mask_columns）会根据每个输出值的来源进行脱敏。只有在分析能够充分证明安全的语句形式下，涉及含有脱敏列的表的语句才会被接受（列、表达式、聚合、窗口函数、联接、CTE、子查询、并集，以及对列出的表使用 *）；其他情况都会在运行前拒绝，并指出具体结构。谓词不会脱敏：针对脱敏列使用 WHERE 仍可缩小结果范围。
5. 有界、已净化、可审计。 设置行数、字节数、单元格数和执行时间上限；在 ClickHouse 上设置每条查询的内存上限（默认 2 GiB，options.max_memory_usage）；在任何解析前检查大小上限；对驱动程序错误文本进行净化。每次调用都会记录审计信息，默认写入平台的状态目录（服务配置对应 /var/log/universal-db-mcp/audit.jsonl，Windows 上对应 %ProgramData%\UniversalDB MCP\logs\audit.jsonl，单用户配置对应 ~/.universal-db-mcp/audit.jsonl）。
6. stdio 不是安全边界。 stdio 注册会在 Agent 内以你的用户身份运行服务器，因此能够运行 Shell 命令或读取文件的 Agent 可以读取 ~/.universal-db-mcp/secrets/ 中的凭据并绕过防护机制直接连接数据库。请使用仅限 SELECT 的登录账号，或在独立服务账号下以 HTTP 模式运行服务器（使用 bearer token，并置于反向代理之后）。

快速开始

从 PyPI 安装

uv tool install 'udbmcp[all]'   # or: pipx install 'udbmcp[all]'
udbmcp add-connection            # writes ~/.universal-db-mcp/config.yaml, secrets in private files beside it
udbmcp configure-agents          # registers it with Claude Code, Claude Desktop, Cursor, VS Code, Cline

[all] 会安装 PostgreSQL、MySQL/MariaDB、ClickHouse 和 Oracle（thin mode）驱动；SQLite 无需驱动。SQL Server（udbmcp[mssql]）和 Db2 （udbmcp[db2]）也需要各自厂商的客户端库。PyPI 上的 wheel 就是该版本签名包中携带的 wheel，并通过 PEP 740 证明上传。请从类似这样的安装中运行 configure-agents，不要通过 uvx 运行：uvx 会从 uv 会清理的缓存中运行，而 configure-agents 拒绝注册位于该缓存中的解释器。

从源代码安装

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e '.[dev]'
.venv/bin/python examples/sqlite-demo/create_demo.py   # synthetic fixture
UDBMCP_CONFIG=examples/sqlite-demo/config.yaml .venv/bin/python -m universal_db_mcp serve --transport stdio

使用 .venv/bin/udbmcp configure-agents 将服务注册到你的 Agent（Claude Code、Claude Desktop、Cursor、VS Code、Cline 等； docs/claude-code-integration.md）。它会使用 python -I（隔离模式）写入启动命令，因此必须像上文所述，将软件包及其依赖安装在虚拟环境中；系统会拒绝 pip install --user 或仅使用 PYTHONPATH 的配置。若你的用户有权限读取系统配置，则会注册该配置（/etc/universal-db-mcp/config.yaml，Windows 上为 %ProgramData%\UniversalDB MCP\config.yaml），否则会注册每用户配置 ~/.universal-db-mcp/config.yaml；如需选择其他配置，请先导出绝对路径形式的 UDBMCP_CONFIG。.deb 会附带所有用户均可读取的系统配置，因此在 .deb 主机上，请先将其权限设为 root:udbmcp 0640 （docs/claude-code-integration.md）。

udbmcp add-connection 会以交互方式添加连接，并以私有权限存储其密钥；udbmcp doctor 会检查配置、密钥，以及（使用 --connectivity 时）每个数据库。

使用容器映像

docker pull ghcr.io/alghanim/universal-db-mcp:0.2.0
gh attestation verify oci://ghcr.io/alghanim/universal-db-mcp:0.2.0 --repo alghanim/universal-db-mcp

该工具已在官方 MCP Registry 中登记为 io.github.alghanim/universal-db-mcp，因此可以通过浏览注册表的客户端进行安装。请以只读方式挂载配置及其密钥，并按 docs/offline-deployment.md（容器模式）中的说明，通过 stdio 或 HTTP 运行。该映像不包含 SQL Server 驱动；同一章节说明了如何添加 Microsoft 的驱动。

最简连接配置

connections:
  sales:
    type: postgres
    host: pg.example.internal
    port: 5432
    database: sales
    username_file: /etc/universal-db-mcp/secrets/sales.user   # 0600, owned by the service account
    password_file: /etc/universal-db-mcp/secrets/sales.pw
    allowed_schemas: [reporting]
    tls:
      enabled: true
      ca_file: /etc/universal-db-mcp/ca/internal-ca.pem

config.example.yaml 按数据库引擎介绍了所有设置。

离线安装（隔离网络环境）

制品	平台	状态
.deb	Ubuntu 24.04 x86-64	发布门禁：无网络情况下进行安装、升级、回滚和拒绝情形测试
.pkg	macOS arm64	通过发布门禁；未签名（尚无 Developer ID）
.msi	Windows x64	使用 WiX 编译，并在 PowerShell 下测试自定义操作；尚未在 Windows 主机上运行
离线包	以上任一平台	使用发布密钥签名；scripts/install_offline.sh
容器映像	linux/amd64，联网主机	ghcr.io/alghanim/universal-db-mcp，由 CI 根据每个版本的签名包构建，并带有来源证明（docs/offline-deployment.md）

请参阅 docs/offline-deployment.md；对于通过发布 U 盘安装的站点，请参阅 docs/site-upgrade-runbook.md（可使用 scripts/package/release_usb.sh 构建发布 U 盘）。简要步骤如下：

# staging machine (authorized for network): the bundle is signed with the release
# key (docs/offline-build.md; scripts/package/release_usb.sh builds a whole stick)
python scripts/prepare_offline_bundle.py --profile linux-x86_64-ubuntu24.04-cp312 --out out/bundle \
  --signing-key udbmcp-release.pem

# target machine (offline), after the trust bootstrap in docs/offline-deployment.md,
# which installs the public key once its fingerprint matches one received out of band:
sudo UDBMCP_RELEASE_PUBKEY=/etc/universal-db-mcp/keys/release.pub.pem \
  bash /usr/local/lib/udbmcp-trust/install_offline.sh out/bundle/universal-db-mcp-*/ /opt/universal-db-mcp
# the installer does not create the config: start from the bundle's template, readable by the service only
sudo install -m 640 -o root -g udbmcp out/bundle/universal-db-mcp-*/config-templates/config.yaml /etc/universal-db-mcp/config.yaml
sudo -u udbmcp /opt/universal-db-mcp/venv/bin/python -m universal_db_mcp doctor --config /etc/universal-db-mcp/config.yaml

在根据已安装的发布密钥验证 Ed25519 签名之前，不会运行来自任何软件包或 U 盘的内容。若软件包中签名的 release_seq 早于已安装版本，安装程序会拒绝安装，除非你明确请求降级：脚本使用 --allow-downgrade，.deb 使用 UDBMCP_ALLOW_DOWNGRADE=1，.pkg 使用其指定的一次性标志文件；对于本版本的 MSI，需先卸载较新版本，再设置 UDBMCP_ALLOW_DOWNGRADE=1（Windows Installer 会拒绝在较新版本之上安装任何较旧的 MSI）。 在容器模式下，scripts/load_images_offline.sh 会保留一个由 root 所有的版本记录（/var/lib/universal-db-mcp/release.json），并以同样方式拒绝较旧的软件包。

验证

• **测试：**超过 12,000 个单元测试，由 GitHub Actions CI 在 ubuntu-24.04 上运行，并在 macOS 上本地运行；ruff 和 mypy --strict 均通过。 IMPLEMENTATION_STATUS.md（第 3f 节）记录了最新统计数据。
• **真实数据库：**上文的版本矩阵，以及针对 scripts/fixtures/start_mock_dbs.sh 中模拟数据库运行的 scripts/live_evidence.py（docs/mock-environment.md）。
• 软件包：.deb 和 .pkg 发布门禁，以及离线升级门禁（docs/acceptance-tests.md）。
• **供应链：**每个平台都使用固定版本且经过哈希校验的锁定文件，并通过 pip-audit 检查。
• **模糊测试：**每次推送到 main 后以及每周都会使用 Atheris 对 SQL 防护机制进行模糊测试（tests/fuzz/）：任何既未接受输入也未明确拒绝输入的情况都会导致运行失败。

尚未在任何环境中验证：在真实 Windows 主机上运行 MSI，以及在真实 macOS 上运行 .pkg 安装器。

开发

.venv/bin/python -m pytest -o addopts='' -q tests                 # the whole suite
UDBMCP_LIVE_FIXTURES=1 UDBMCP_DOCKER_TESTS=1 \
  .venv/bin/python -m pytest -o addopts='' -q tests               # plus the live-database and container tests
.venv/bin/ruff check src tests scripts && .venv/bin/mypy --strict src

使用本地模拟数据库的测试仅在设置 UDBMCP_LIVE_FIXTURES=1 时运行，因此软件包门禁不会等待已暂停或不存在的数据库；真实 dpkg 容器序列仅在设置 UDBMCP_DOCKER_TESTS=1 时运行。软件包构建器测试需要虚拟环境中安装 pip：运行 uv sync 后，执行 uv pip install --python .venv/bin/python --require-hashes -r .github/ci-pip-requirements.txt。

CI。 .github/workflows/ci.yml 是一个 GitHub Actions 工作流（ubuntu-24.04，CPython 3.12）：运行单元测试套件（包括在 pwsh 下运行的 MSI 自定义操作测试）、ruff、mypy --strict、prepare_offline_bundle.py --check-locks，并对每个锁定文件运行 pip-audit。Actions 均固定到提交 SHA。每个拉取请求以及每次推送到 main 时都会运行，并同时启动两个任务：最慢的安装器和打包测试文件在 installer-tests 中运行，checks 则运行其余测试和所有其他检查。.github/workflows/audit.yml 每周运行相同的 pip-audit，因此即使两次提交之间出现新的安全公告，也会导致一次运行失败。Dependabot 每月提出分组更新。 tests/unit/test_hardening_2026_09_27_ci_hygiene.py 用于检查 CI 配置本身（固定的 actions、pytest 选项、两个任务合起来恰好运行每项测试一次、没有隐藏在 conftest 或辅助代码中的跳过项或钩子，以及代码树中没有编译文件或符号链接）；它只是一个预警机制，并非沙箱，因此 conftest、测试辅助代码和 CI 文件的更改仍需经过审查。Dependabot 更新 requirements/runtime.in 后，请刷新并审查锁定文件（docs/offline-build.md）。

文档目录

文档	用途
docs/architecture.md	组件、数据流、进程边界、执行限制
docs/security.md	威胁模型、策略、掩码、审计、机密信息、TLS
docs/tools.md	MCP 工具约定（29 个 db_* 工具）
docs/session-safety.md	每个连接对服务端会话的操作，以及如何确保 Agent 读取不会影响生产环境
docs/driver-matrix.md	各引擎的驱动、原生依赖项、配置 SQL、测试状态
docs/oracle-connect-modes.md	Oracle 厚模式（旧版密码验证器）、SID 和 TNS 别名连接、TLS
docs/db2-tls-setup.md	Db2 TLS 启用操作指南
docs/claude-code-integration.md	将服务注册到 Claude Code 和其他 Agent，以及内部网关设置
docs/offline-build.md	阶段 A：在暂存机器上准备捆绑包
docs/offline-deployment.md	阶段 B：在气隙环境中安装（.deb、.pkg、.msi、捆绑包、容器）
docs/offline-upgrade-rollback.md	升级和回滚
docs/site-upgrade-runbook.md	逐步站点升级指南，包含此版本的行为变更（随安装介质以 UPGRADE-README.md 的形式提供）
docs/acceptance-tests.md	发布门禁及其运行方法
docs/mock-environment.md	用于实时验证的本地模拟数据库
docs/adding-connectors.md	如何添加引擎适配器
docs/troubleshooting.md	常见故障和 doctor 输出
IMPLEMENTATION_STATUS.md	已实现／已验证／待处理事项清单
SECURITY.md	如何报告漏洞、受支持的版本，以及修复如何送达气隙站点
site/index.html	产品主页，由 .github/workflows/pages.yml 发布（tests/unit/test_landing_page.py 会重新运行页面所展示的每项防护判定）

报告漏洞

请通过 GitHub 私密漏洞报告渠道私下报告安全问题，切勿在公开议题中报告。SECURITY.md 说明了需要提供哪些信息，以及修复如何送达气隙站点。本项目由 universal-db-mcp 维护者维护，不公布电子邮件地址：.deb 的 Maintainer 字段中填写的是 Debian 要求提供的占位地址，使用保留的 .invalid 域名，因此无人会收到邮件。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。两者都会随 wheel 一同提供，也会放在离线捆绑包的 licenses/ 目录中；.deb 会在其 DEP-5 文件 /usr/share/doc/universal-db-mcp/copyright 中声明许可证，NOTICE 文件也在其旁边。第三方组件保留各自的许可证：捆绑包会在 sbom/cyclonedx.json 中列出这些许可证，每个 wheelhouse/ 中的 wheel 也都附带其许可证文件。

Db2 连接器的 ibm_db wheel 包含 IBM Data Server Driver for ODBC 和 CLI 可再发行组件，IBM 允许将其作为应用程序的一部分进行分发。这些组件未经修改随包提供，并附有 IBM 的许可证和声明文件，且受这些文件约束（参见 NOTICE）。Db2 和 IBM 是 International Business Machines Corporation 的商标，此处仅用于指代数据库及其驱动程序。Microsoft 的 SQL Server ODBC Driver 和 Oracle 的 Instant Client 不会随包再分发：站点需从供应商处安装。