MCP 集成
什么是 MCP？
MCP（Model Context Protocol）是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。
AI 助手 → DBX MCP → 你的数据库 → 返回结果
↘ DBX 桌面端（打开或展示结果）快速开始
配置 AI 助手
在项目目录创建 .mcp.json：
{
"mcpServers": {
"dbx": {
"command": "npx",
"args": ["-y", "@dbx-app/mcp-server"]
}
}
}如果使用全局安装，可将 command 改为 dbx-mcp-server。连接 allowlist 和执行权限统一在 DBX 设置 → MCP 中管理，常规客户端配置不需要权限环境变量。Windows 便携版请将 DBX_DATA_DIR 设置为 DBX.exe 同级的 data 目录。
开始使用
在 AI 助手中直接使用自然语言：
- "列出我的数据库连接"
- "查看 local-pg 上有哪些表"
- "查看 users 表的结构"
- "查询最近 7 天的订单数量"
- "打开 orders 表"（需要 DBX 运行中）
支持的 AI 助手
| AI 助手 | 配置方式 |
|---|---|
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
| Windsurf | MCP 配置 |
| VS Code + Copilot | MCP 扩展/配置 |
工具列表
DBX MCP 当前提供 12 个工具：
| 工具 | 说明 |
|---|---|
dbx_list_connections | 列出当前 MCP 会话可见的连接 |
dbx_add_connection | 添加连接到 DBX 存储 |
dbx_remove_connection | 从 DBX 存储删除连接 |
dbx_list_tables | 列出表、视图或集合 |
dbx_describe_table | 返回列定义和表元数据 |
dbx_get_schema_context | 返回适合 AI 使用的紧凑 Schema 上下文 |
dbx_execute_query | 执行 SQL 或支持的 MongoDB shell 命令，最多返回 100 行 |
dbx_open_session | 为 SQL 连接打开固定后端连接的有状态查询会话 |
dbx_close_session | 关闭会话并释放固定连接资源 |
dbx_execute_redis_command | 执行 Redis 命令 |
dbx_open_table | 在运行中的 DBX 桌面端打开表 |
dbx_execute_and_show | 执行查询并在 DBX 中展示结果 |
启用连接作用域后，修改连接和桌面 UI 工具会被隐藏。
有状态查询会话
普通 dbx_execute_query 调用彼此独立。需要保持数据库 Session 状态时，先调用 dbx_open_session，再把返回的 sessionId 传给后续 dbx_execute_query：
USE或数据库上下文切换- 临时表
- Session 变量和设置
- 需要固定连接的显式事务或多步诊断
会话只支持 SQL 连接，并固定到一个连接和数据库。未知、已关闭或过期的 sessionId 会失败，不会静默退化为普通查询。完成后应调用 dbx_close_session；空闲 30 分钟的会话会被回收，同时最多允许 32 个并发会话。
USE 只有在会话中才有意义，但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。数据库访问
本地连接
这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行；需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。
常见的本地数据库文件路径：
| 平台 | 默认路径 |
|---|---|
| macOS | ~/Library/Application Support/com.dbx.app/dbx.db |
| Linux | ~/.local/share/com.dbx.app/dbx.db |
| Windows | %APPDATA%\com.dbx.app\dbx.db |
DBX_DATA_DIR 必须指向包含 dbx.db 的目录，而不是数据库文件本身。Windows 便携版通常是 DBX.exe 同级的 data 目录。
原生 SQL、独立 Redis 和 MongoDB 等路径可以由 MCP 直接执行。SSH、集群、厂商专用、外部驱动以及 Agent/JDBC 连接是否可用，取决于连接配置和本机已安装的 DBX 组件；不要从“DBX 支持该数据库”推断 MCP 原生包已经内置全部运行时。
DuckDB 使用独立的 DBX DuckDB 驱动。通过本地 MCP 查询 DuckDB 前，需要先在 DBX Driver Manager 中安装该驱动。MCP 二进制只包含 sidecar 客户端，不会内置 DuckDB 引擎。
Agent/JDBC 数据库
Oracle、金仓KingbaseES 和虚谷需要匹配的 DBX 原生 Agent，但不需要 JRE。达梦、DB2、Hive、Trino、Snowflake、SAP HANA 等 JDBC Agent 数据库需要匹配的 Agent、JDBC 驱动和 JRE。请先在 DBX 中安装所需组件，再使用 MCP。
DBX Web / Docker 模式
设置 DBX_WEB_URL 后，MCP 会使用部署的 DBX Web 后端，而不是读取本机连接。如果 Web 登录启用了密码保护，还要设置 DBX_WEB_PASSWORD，值为 Web 登录页使用的密码。
DBX Web 请求遵循标准系统代理环境变量：https 地址读取 HTTPS_PROXY/https_proxy，http 地址读取 HTTP_PROXY/http_proxy，ALL_PROXY/all_proxy 作为兜底，NO_PROXY/no_proxy（逗号分隔的主机列表，例如 localhost,127.0.0.1,.internal.example）作为绕过列表。代理值为空或未设置时直连（不走代理）。支持 HTTP、HTTPS 与 SOCKS5 代理（http://127.0.0.1:7890 或 socks5://127.0.0.1:1080）；需要认证的代理使用标准 user:password@host:port URL 形式，例如 http://admin:admin123@127.0.0.1:7890。如需为每次 DBX Web 请求附加自定义请求头（例如网关前的令牌认证），将 DBX_WEB_HEADERS 设置为 JSON 对象，键为请求头名称、值为字符串，例如 {"Authorization":"Bearer <token>"}。目标为自签名 HTTPS 时，证书验证默认开启：设置 DBX_WEB_INSECURE_SKIP_VERIFY=1 可跳过验证，或设置 DBX_WEB_CA_CERT 指向 PEM/DER CA 文件以信任私有 CA。同样的变量在 DBX CLI 的 Web 模式下同样生效。
DBX Web 和 Docker 同样需要独立 DuckDB 驱动。首次启动后可通过 Driver Manager 安装；Docker 会把驱动保存到 /app/data/agents，挂载 /app/data 数据卷后升级容器不会丢失。
桌面 UI 工具
dbx_open_table 和 dbx_execute_and_show 要求 DBX 桌面端正在运行，并且在 Web 模式或连接作用域隐藏 UI 工具时不可用。其他工具是否需要 Desktop 取决于该连接是原生执行还是 bridge/Agent 路径。
安全和环境变量
DBX 在 设置 → MCP 中保存一份权威策略，并在每次请求时重新读取：
| 权限模式 | 允许的操作 |
|---|---|
| 只读 | 查询和元数据读取 |
| 数据读写 | 普通插入、带有效过滤条件的更新/删除、范围明确的 MongoDB 修改和普通 Redis 写入 |
| 完全访问 | 额外允许大范围更新/删除、DDL、TRUNCATE、MongoDB 破坏性操作和 Redis FLUSH* |
WHERE TRUE、WHERE 1 = 1、_id: {$exists: true} 或不透明 MongoDB 过滤器仍按高风险处理。连接自身只读、生产库保护、数据库账号权限和 MCP 连接 allowlist 在任何模式下都是权限上限。
新版 Server 不允许 DBX_MCP_ALLOW_WRITES 或 DBX_MCP_ALLOW_DANGEROUS_SQL 放宽 DBX 中央策略。为兼容升级，在中央策略首次保存前，旧配置中的 DBX_MCP_ALLOW_WRITES=0（或 false）仍会保持 MCP 只读；策略保存后仅以中央策略为准，并忽略旧权限变量。旧连接 scope 变量只能进一步收窄 DBX allowlist。
| 变量 | 用途 |
|---|---|
DBX_DATA_DIR | 覆盖本地 DBX 数据目录 |
DBX_WEB_URL | 使用 DBX Web/Docker 后端 |
DBX_WEB_PASSWORD | 登录 DBX Web |
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY | DBX Web 请求的标准系统代理变量；空值表示不走代理。认证格式 http://user:pass@host:port |
NO_PROXY | 上述代理的标准绕过列表（逗号分隔主机） |
DBX_WEB_HEADERS | DBX Web 请求附加的请求头 JSON 对象，例如 {"Authorization":"Bearer token"} |
DBX_WEB_INSECURE_SKIP_VERIFY | 1/true 时跳过 TLS 证书验证（用于自签名 DBX Web 后端；默认验证） |
DBX_WEB_CA_CERT | DBX Web TLS 验证时信任的 PEM/DER CA 文件 |
DBX_MCP_ALLOW_WRITES | 仅用于升级兼容：0/false 使尚未配置的策略保持只读 |
DBX_MCP_SCOPE_CONNECTION_ID | 兼容旧配置：限制为一个连接 ID |
DBX_MCP_SCOPE_CONNECTION_IDS | 兼容旧配置：限制为多个连接 ID |
DBX_MCP_SCOPE_CONNECTION_NAME | 限制为一个连接名称 |
DBX_MCP_SCOPE_DATABASE | 限制为一个数据库 |
DBX_MCP_DEBUG_SQL | 临时诊断时输出 SQL |
常见问题
系统要求
- Node.js 18.18.0 或更高版本
- 已安装 DBX，并至少配置一个数据库连接
- Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE
- 使用两个桌面 UI 工具时，需要保持 DBX 桌面端运行