160 lines
6.9 KiB
Plaintext
160 lines
6.9 KiB
Plaintext
---
|
||
title: MCP 集成
|
||
description: 通过 Model Context Protocol 让 AI 编程助手查询你的数据库。
|
||
---
|
||
|
||
<Callout type="info">把 AI 助手连接到 DBX，即可查看数据库结构、查询数据，并在 DBX 中打开结果。</Callout>
|
||
|
||
## 什么是 MCP？
|
||
|
||
MCP（Model Context Protocol）是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。
|
||
|
||
```text
|
||
AI 助手 → DBX MCP → 你的数据库 → 返回结果
|
||
↘ DBX 桌面端（打开或展示结果）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
<Steps>
|
||
<Step>
|
||
### 安装 MCP Server
|
||
|
||
```bash
|
||
npm install -g @dbx-app/mcp-server
|
||
```
|
||
|
||
npm 会自动安装当前平台需要的依赖。不要使用 `--no-optional`。
|
||
</Step>
|
||
<Step>
|
||
### 配置 AI 助手
|
||
|
||
在项目目录创建 `.mcp.json`：
|
||
|
||
```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` 目录。
|
||
</Step>
|
||
<Step>
|
||
### 开始使用
|
||
|
||
在 AI 助手中直接使用自然语言：
|
||
|
||
- "列出我的数据库连接"
|
||
- "查看 local-pg 上有哪些表"
|
||
- "查看 users 表的结构"
|
||
- "查询最近 7 天的订单数量"
|
||
- "打开 orders 表"（需要 DBX 运行中）
|
||
</Step>
|
||
</Steps>
|
||
|
||
## 支持的 AI 助手
|
||
|
||
| AI 助手 | 配置方式 |
|
||
| --- | --- |
|
||
| Claude Code | `.mcp.json` |
|
||
| Cursor | `.cursor/mcp.json` |
|
||
| Windsurf | MCP 配置 |
|
||
| VS Code + Copilot | MCP 扩展/配置 |
|
||
|
||
## 工具列表
|
||
|
||
DBX MCP 当前提供 10 个工具：
|
||
|
||
| 工具 | 说明 |
|
||
| --- | --- |
|
||
| `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_execute_redis_command` | 执行 Redis 命令 |
|
||
| `dbx_open_table` | 在运行中的 DBX 桌面端打开表 |
|
||
| `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 |
|
||
|
||
启用连接作用域后，修改连接和桌面 UI 工具会被隐藏。
|
||
|
||
## 数据库访问
|
||
|
||
### 本地连接
|
||
|
||
这是默认模式。MCP 使用 DBX 中保存的连接配置。执行数据库查询时不要求 DBX 桌面端保持运行。
|
||
|
||
常见的本地数据库文件路径：
|
||
|
||
| 平台 | 默认路径 |
|
||
| --- | --- |
|
||
| 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` 目录。
|
||
|
||
PostgreSQL、MySQL、SQLite、兼容 SQL 数据库、独立 Redis 和 MongoDB 可以直接查询。部分 SSH、集群、厂商专用以及 Agent/JDBC 连接需要先安装对应的 DBX 组件。
|
||
|
||
### Agent/JDBC 数据库
|
||
|
||
Oracle、人大金仓和虚谷需要匹配的 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 登录页使用的密码。
|
||
|
||
### 桌面 UI 工具
|
||
|
||
`dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行。其他查询工具可以在 DBX 关闭时使用。
|
||
|
||
## 安全和环境变量
|
||
|
||
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 |
|
||
| `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 |
|
||
|
||
## 常见问题
|
||
|
||
<Accordions>
|
||
<Accordion title="npm 没有安装当前平台包">不要使用 `--no-optional`，重新安装 `@dbx-app/mcp-server`，并用 `node -p 'process.platform + "-" + process.arch'` 检查平台。Alpine Linux 默认使用 musl，目前不在 Linux 发布包支持范围内。</Accordion>
|
||
<Accordion title="找不到 dbx.db">将 `DBX_DATA_DIR` 设置为包含 `dbx.db` 的目录。Windows 便携版通常是 `DBX.exe` 旁边的 `data` 目录。</Accordion>
|
||
<Accordion title="提示 DBX 未运行">只有 `dbx_open_table` 和 `dbx_execute_and_show` 需要桌面端运行；本地查询工具可以在 DBX 关闭时执行。</Accordion>
|
||
<Accordion title="Agent/JDBC 数据库无法启动">在 DBX Driver Manager 中安装或更新匹配的 Agent、JDBC 驱动和 JRE。厂商专有驱动不会随 MCP 原生包发布。</Accordion>
|
||
<Accordion title="出现 better-sqlite3 或 Node ABI 错误">MCP 不需要 `better-sqlite3`。请先升级 `@dbx-app/mcp-server`；如果错误来自 `@dbx-app/cli`，请按照 CLI 的安装要求处理，因为它们是两个独立的包。</Accordion>
|
||
</Accordions>
|
||
|
||
## 系统要求
|
||
|
||
- Node.js 18.18.0 或更高版本
|
||
- 已安装 DBX，并至少配置一个数据库连接
|
||
- Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE
|
||
- 使用两个桌面 UI 工具时，需要保持 DBX 桌面端运行
|