228 lines
6.4 KiB
Plaintext
228 lines
6.4 KiB
Plaintext
---
|
||
title: MCP 集成
|
||
description: 通过 MCP 协议让 Claude Code、Cursor 等 AI 编程助手直接查询你的数据库。
|
||
---
|
||
|
||
<Callout type="info">
|
||
一行配置，让 AI 编程助手直接查询你的数据库。支持 Claude Code、Cursor、Windsurf、VS Code Copilot。
|
||
</Callout>
|
||
|
||
## 什么是 MCP？
|
||
|
||
MCP（Model Context Protocol）是一个开放协议，让 AI 编程助手能够调用外部工具。DBX 的 MCP Server 把你在 DBX 中配置的数据库连接暴露给 AI 助手，这样你可以用自然语言查询数据库，AI 自动生成并执行 SQL。
|
||
|
||
```
|
||
你："查看 orders 表最近 7 天的订单量趋势"
|
||
|
||
AI 助手 → MCP Server → 你的数据库 → 返回结果
|
||
↓
|
||
DBX 的连接配置（含密码）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
<Steps>
|
||
<Step>
|
||
### 安装 MCP Server
|
||
|
||
```bash
|
||
npm install -g @dbx-app/mcp-server
|
||
```
|
||
</Step>
|
||
<Step>
|
||
### 配置 AI 助手
|
||
|
||
在你的工作目录创建 `.mcp.json`：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"dbx": {
|
||
"command": "npx",
|
||
"args": ["-y", "@dbx-app/mcp-server"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Step>
|
||
<Step>
|
||
### 开始使用
|
||
|
||
在 AI 助手中直接用自然语言说：
|
||
|
||
- "列出我的数据库连接"
|
||
- "查看 local-pg 上有哪些表"
|
||
- "查看 users 表的结构"
|
||
- "查询最近 7 天的订单数量"
|
||
- "打开 orders 表"（需要 DBX 运行中）
|
||
</Step>
|
||
</Steps>
|
||
|
||
## 支持的 AI 助手
|
||
|
||
| 助手 | 配置方式 |
|
||
|---|---|
|
||
| Claude Code | `.mcp.json`（原生支持） |
|
||
| Cursor | `.cursor/mcp.json` |
|
||
| Windsurf | `.windsurfrules` |
|
||
| VS Code + Copilot | MCP 扩展 |
|
||
|
||
## 工具列表
|
||
|
||
DBX MCP Server 提供以下工具，AI 助手会根据你的需求自动调用：
|
||
|
||
### `dbx_list_connections`
|
||
|
||
列出 DBX 中所有已配置的数据库连接。
|
||
|
||
**示例对话：**
|
||
> "列出我的数据库连接"
|
||
|
||
**返回：**
|
||
```
|
||
| Name | Type | Host | Port | Database |
|
||
| -------- | -------- | --------- | ---- | -------- |
|
||
| local-pg | postgres | 127.0.0.1 | 5432 | |
|
||
| prod-db | mysql | db.example| 3306 | myapp |
|
||
```
|
||
|
||
### `dbx_list_tables`
|
||
|
||
列出指定连接的表和视图。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | DBX 连接名称 |
|
||
| `schema` | 否 | Schema 名称（默认 public） |
|
||
|
||
### `dbx_describe_table`
|
||
|
||
获取表的列定义，AI 用它来理解你的数据结构。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | DBX 连接名称 |
|
||
| `table` | 是 | 表名 |
|
||
| `schema` | 否 | Schema 名称（默认 public） |
|
||
|
||
**返回：**
|
||
```
|
||
| Column | Type | Nullable | Default | Comment |
|
||
| ----------- | --------- | -------- | ------- | ------- |
|
||
| id (PK) | integer | NO | | |
|
||
| user_id | integer | NO | | 用户 ID |
|
||
| total | numeric | NO | 0 | 订单金额 |
|
||
| created_at | timestamp | NO | now() | |
|
||
```
|
||
|
||
### `dbx_execute_query`
|
||
|
||
执行 SQL 查询，返回结果（最多 100 行）。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | DBX 连接名称 |
|
||
| `sql` | 是 | SQL 查询语句 |
|
||
|
||
### `dbx_add_connection`
|
||
|
||
添加新的数据库连接。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `name` | 是 | 连接名称 |
|
||
| `db_type` | 是 | 数据库类型（postgres、mysql、sqlite、redis 等） |
|
||
| `host` | 是 | 数据库主机 |
|
||
| `port` | 是 | 数据库端口 |
|
||
| `username` | 否 | 用户名 |
|
||
| `password` | 否 | 密码 |
|
||
| `database` | 否 | 默认数据库名 |
|
||
| `ssl` | 否 | 是否启用 SSL（默认 false） |
|
||
|
||
**示例对话：**
|
||
> "添加一个 PostgreSQL 连接，名称 prod-db，地址 db.example.com:5432"
|
||
|
||
### `dbx_remove_connection`
|
||
|
||
删除数据库连接。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | 要删除的连接名称 |
|
||
|
||
**示例对话：**
|
||
> "删除 test-db 连接"
|
||
|
||
### `dbx_open_table`
|
||
|
||
在 DBX 桌面端打开指定表。**需要 DBX 正在运行。**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | DBX 连接名称 |
|
||
| `table` | 是 | 表名 |
|
||
| `database` | 否 | 数据库名 |
|
||
| `schema` | 否 | Schema 名称 |
|
||
|
||
DBX 会自动新开一个 tab 显示数据，窗口自动置前。
|
||
|
||
### `dbx_execute_and_show`
|
||
|
||
在 DBX 桌面端执行 SQL 并展示结果。**需要 DBX 正在运行。**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `connection_name` | 是 | DBX 连接名称 |
|
||
| `sql` | 是 | SQL 查询语句 |
|
||
| `database` | 否 | 数据库名 |
|
||
|
||
## 工作原理
|
||
|
||
### 连接配置
|
||
|
||
MCP Server 从 DBX 的 SQLite 数据库读取连接信息：
|
||
|
||
| 平台 | 路径 |
|
||
|---|---|
|
||
| macOS | `~/Library/Application Support/com.dbx.app/dbx.db` |
|
||
| Linux | `~/.config/com.dbx.app/dbx.db` |
|
||
| Windows | `%APPDATA%\com.dbx.app\dbx.db` |
|
||
|
||
### UI 联动
|
||
|
||
`dbx_open_table` 和 `dbx_execute_and_show` 通过本地 HTTP 接口与运行中的 DBX 应用通信：
|
||
|
||
```
|
||
AI 助手 → MCP Server → HTTP localhost → DBX 后端 → Tauri 事件 → 前端打开 tab
|
||
```
|
||
|
||
### 支持的数据库
|
||
|
||
MCP 查询支持 PostgreSQL 和 MySQL（及兼容数据库：Doris、StarRocks 等）。UI 联动（打开表）支持 DBX 已支持的所有数据库类型。
|
||
|
||
## 常见问题
|
||
|
||
<Accordions>
|
||
<Accordion title="MCP Server 连不上数据库">
|
||
检查 DBX 中该连接是否能正常连接。MCP Server 使用相同的连接配置和密码。确认数据库服务正在运行，网络可达。
|
||
</Accordion>
|
||
<Accordion title="dbx_open_table 报 'DBX is not running'">
|
||
需要先启动 DBX 桌面应用。UI 联动功能依赖 DBX 运行时的本地 HTTP 服务（端口 4224）。
|
||
</Accordion>
|
||
<Accordion title="连接名称找不到">
|
||
连接名称匹配不区分大小写，但需要和 DBX 中配置的名称一致。用 `dbx_list_connections` 查看所有可用名称。
|
||
</Accordion>
|
||
<Accordion title="查询超时">
|
||
MCP Server 的查询超时为 30 秒。如果查询较慢，考虑添加索引或简化查询。也可以让 AI 助手先用 `dbx_describe_table` 了解表结构，再生成优化后的查询。
|
||
</Accordion>
|
||
<Accordion title="Docker 环境下如何使用 MCP？">
|
||
Docker 部署的 DBX 同样支持 MCP。MCP Server 会读取 Docker 容器内的连接配置。确保 MCP Server 能访问到 DBX 的配置目录。
|
||
</Accordion>
|
||
</Accordions>
|
||
|
||
## 系统要求
|
||
|
||
- [DBX](https://github.com/t8y2/dbx) 已安装并配置了至少一个数据库连接
|
||
- Node.js 18+
|
||
- UI 联动功能需要 DBX v0.3.9+
|