Files
dbx/docs/content/docs/mcp.cn.mdx
T

150 lines
6.0 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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`。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_ALLOW_WRITES=0` 可强制只读。`DROP`、`TRUNCATE`、`ALTER`、Redis 破坏性命令以及危险 MongoDB 修改默认仍会阻止,除非设置 `DBX_MCP_ALLOW_DANGEROUS_SQL=1`。
| 变量 | 用途 |
| --- | --- |
| `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 |
| `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 |
| `DBX_WEB_PASSWORD` | 登录 DBX Web |
| `DBX_MCP_ALLOW_WRITES` | 设置为 `0` 强制只读 |
| `DBX_MCP_ALLOW_DANGEROUS_SQL` | 允许危险 SQL、Redis 和 MongoDB 操作 |
| `DBX_MCP_SCOPE_CONNECTION_ID` | 限制为一个连接 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 桌面端运行