内容
# DBeaver MCP 服务器
DBeaver MCP 服务器是一款 Eclipse/OSGi 插件，运行在 DBeaver 中，通过本地 MCP 流式 HTTP 服务器将已配置的数据库连接暴露给 AI 代理。
该插件直接使用 DBeaver 的连接注册表、驱动程序和实时会话。它不读取或解密 `credentials-config.json`。
## 从 GitHub Pages 安装
1. 在 DBeaver 中，打开 **帮助 -> 安装新软件...**。
2. 添加以下更新站点：
```text
https://bachden.github.io/dbeaver-mcp-server/
```
3. 选择 **DBeaver MCP 服务器** 并完成安装向导。
4. 在提示时重启 DBeaver。
该 URL 是一个用于 DBeaver 的 p2 仓库。根目录可能不会在浏览器中呈现 HTML 页面；DBeaver 直接读取 `p2.index`、`artifacts.xml.xz` 和 `content.xml.xz`。
## 人机协作
该插件遵循 **所见即所得** 的规则：
- `list_connections` 列出打开和关闭的连接，并包含一个 `connected` 字段。
- `get_schema`、`run_query` 和 `execute_sql` 仅使用已在 DBeaver 中打开的连接。
- 插件从不自动打开数据库连接或代表用户显示凭证提示。
- 当连接关闭时，工具返回错误并要求用户在 DBeaver 中手动打开它。
- 隧道、凭证、MFA 和连接决策仍然由用户在 DBeaver UI 中控制。
## 工具
| 工具 | 描述 |
|------|-------------|
| `list_connections` | 列出连接、其 `connectionId`、端点和 `connected` 状态。 |
| `get_schema` | 通过点状 `path` 浏览目录、模式、表和列。 |
| `run_query` | 运行只读 SQL，如 SELECT、WITH、SHOW、EXPLAIN 和 DESCRIBE。 |
| `execute_sql` | 运行任何 SQL，包括 INSERT、UPDATE、DELETE 和 DDL。它可以修改或删除数据。 |
所有三个数据库访问工具都拒绝关闭的连接。
`run_query` 和 `execute_sql` 接受一个可选的 `showOnUi` 布尔值（默认为 `false`）。当为 `true` 时，语句通过可见的 DBeaver SQL 编辑器执行：其结果显示在 DBeaver 结果网格中，并且相同的数据返回给 MCP 调用者。DBeaver 的正常执行确认保持活动状态，并且连接必须已经打开。
## 服务器和 UI
默认端点是：
```text
POST http://127.0.0.1:8722/mcp
```
**DBeaver MCP** 菜单提供：
- **启动服务器**
- **停止服务器**
- **连接...**
- **设置...**
状态栏显示当前服务器状态。启动/停止选择在工作区中持久保存：停止的服务器在 DBeaver 重启后仍然停止，而启用的服务器在 DBeaver 重启后自动启动。
该包通过 `org.jkiss.dbeaver.pluginService` 生命周期在 DBeaver 平台就绪后激活。p2 元数据不强制 `markStarted`，这避免了 Equinox 尝试启动重复的单实例模块。
**窗口 -> 首选项 -> DBeaver MCP 服务器** 页面配置侦听器主机、端口、承载令牌身份验证和用于 Claude Code、Claude Desktop、Codex CLI 或原始 HTTP 的客户端代码段。
服务器支持 `initialize`、`ping`、`tools/list`、`tools/call` 和 JSON-RPC 批次。它不提供 SSE 流。
## 项目布局
```text
dbeaver-mcp-server-plugin-parent
├── pom.xml
├── .github/workflows/
├── dbeaver-mcp-server-plugin
│ ├── META-INF/MANIFEST.MF
│ ├── plugin.xml
│ ├── dbeaver-ci.target
│ ├── pom.xml
│ └── src/
├── dbeaver-mcp-server-plugin.feature
│ ├── feature.xml
│ └── pom.xml
└── dbeaver-mcp-server-plugin.updatesite
├── category.xml
└── pom.xml
```
模块有：
- `dbeaver-mcp-server-plugin-parent`：Maven/Tycho 反应堆。
- `dbeaver-mcp-server-plugin`：OSGi 包。
- `dbeaver-mcp-server-plugin.feature`：可安装的 p2 功能。
- `dbeaver-mcp-server-plugin.updatesite`：p2 仓库。
## 开发设置
要求：
- 已安装 DBeaver 23+。
- Java 21。
- 带有 PDE 和 m2e 的 Eclipse IDE。
- Maven 3.9 或更高版本。
使用 **文件 -> 导入 -> 现有 Maven 项目** 导入仓库根目录。Eclipse 将发现四个反应堆项目。
打开 `dbeaver-mcp-server-plugin/dbeaver-ci.target`，选择 **设置为活动目标平台**，并等待 PDE 完成解析。这是 Tycho 和 GitHub Actions 消耗的相同公共 p2 目标定义。构建中不包含本地 DBeaver 安装路径。
## 构建 p2 更新站点
从仓库根目录运行：
```bash
mvn clean verify
```
Tycho 构建包、功能和 p2 仓库。完整的仓库被复制到：
```text
dist/
├── artifacts.jar
├── content.jar
├── features/
├── plugins/
└── p2.index
```
GitHub Actions 运行相同的 `mvn clean verify` 命令，并通过父 POM 使用 `dbeaver-ci.target`。`dist/` 是稳定的本地更新站点位置。每次构建都会用时间戳替换 `0.1.6.qualifier` 限定符，以便 p2 可以识别新更新。
## 从本地更新站点安装
1. 构建项目以创建 `dist/`。
2. 在 DBeaver 中，打开 **帮助 -> 安装新软件...**。
3. 选择 **添加... -> 本地...** 并选择 `dist/` 目录。
4. 给仓库一个名称，例如 **本地 DBeaver MCP**。
5. 选择 **DBeaver MCP 服务器** 并完成向导。
6. 在提示时重启 DBeaver。
无需复制 JAR 文件、编辑 `bundles.info` 或使用 `dropins/`。正常的安装和更新流程不需要 `-clean`。
## 更新插件
对于本地开发：
1. 重新构建更新站点：
```bash
mvn clean verify
```
2. 在 DBeaver 中，选择 **帮助 -> 检查更新**。
3. 安装新版本，并在提示时重启 DBeaver。
本地仓库保留在 `dist/`，因此在每次构建后无需再次添加。不要卸载和重新安装具有相同时间戳的版本。创建新的限定符或增加基本版本，然后使用 **检查更新**。
如果错误日志在重新安装完全相同的版本后报告 `Another singleton bundle selected`，请完全关闭 DBeaver 并使用以下命令运行一次：
```bash
/Applications/DBeaver.app/Contents/MacOS/dbeaver -clean
```
之后，DBeaver 可以正常启动。
## GitHub Actions 和 Pages
仓库包含两个工作流程：
- **构建和发布 DBeaver 更新站点** 在推送到 `main` 时运行，使用共享的 `dbeaver-ci.target` 构建，并将 `dist/` 部署到 GitHub Pages。
- **验证 DBeaver 更新站点** 在拉取请求中运行，并将 `dist/` 作为构建工件上传。
已发布的更新站点是：
```text
https://bachden.github.io/dbeaver-mcp-server/
```
不要提交 `target/` 或 `dist/`；Maven 在 CI 中重新创建这些工件。
## 连接 AI 代理
禁用身份验证的 Claude Code 示例：
```bash
claude mcp add --transport http dbeaver http://127.0.0.1:8722/mcp
```
启用身份验证时，客户端必须发送：
```text
Authorization: Bearer <token>
```
Codex CLI 示例：
```toml
[mcp_servers.dbeaver]
url = "http://127.0.0.1:8722/mcp"
[mcp_servers.dbeaver.headers]
Authorization = "Bearer <token>"
```
## 安全
- 服务器默认绑定到 `127.0.0.1`。
- 在绑定到 LAN 地址或 `0.0.0.0` 时启用承载令牌身份验证。
- `execute_sql` 接受不受限制的 SQL，可以修改或删除数据。
- `run_query` 过滤器不是数据库权限的替代品。当需要严格的写入限制时，请使用只读数据库帐户。
- 用户必须在 DBeaver 中打开连接，然后代理才能访问该数据库。
- 服务器可以随时从菜单或状态栏停止。
