内容
<div align="center">
# ⚡ 开源数据库中间件平台
**让大型语言模型代理安全地访问你的数据库**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
**简体中文** | [English](README_EN.md)
</div>
---
基于 [MCP 协议](https://modelcontextprotocol.io) 的多数据源数据库工具，通过 stdio 本地进程与 Claude Desktop / Cursor / Trae 等 AI 客户端即插即用。
**支持数据库**：MySQL · Oracle · 达梦 · PostgreSQL · Vastbase · openGauss · SQLite
**核心能力**：多数据源一键切换 · 三层白名单安全护栏 · 影响行数预检 · 事务支持 · CSV/JSON 导入导出 · 跨库 Schema Diff · 插件化驱动扩展
---
## 🚀 快速开始
```bash
git clone https://github.com/cjp1016/open-db-mcp.git
cd open-db-mcp
uv sync # 安装依赖
uv run open-db-mcp init # 生成 ~/.open-db-mcp/ 配置
uv run open-db-mcp doctor # 健康检查
```
### 配置数据源
编辑 `~/.open-db-mcp/datasources.json`：
```json
{
"MY_MYSQL": {
"driver": "mysql",
"url": "jdbc:mysql://127.0.0.1:3306/test_db",
"user": "root",
"password": "env:DB_PASSWORD"
}
}
```
- `driver`：简写（`mysql` / `oracle` / `dm` / `postgres` / `sqlite`）或完整 JDBC 类名
- `password`：支持明文或安全引用（`env:变量名` / `keyring:` / `cmd:`）
- 可选参数：`pool_min`、`pool_max`、`max_affected_rows`
### 注册到 MCP 客户端
**最简配置**（使用默认路径 `config/datasources.json`）：
```json
{
"mcpServers": {
"open-db-mcp": {
"command": "open-db-mcp",
"args": ["run"]
}
}
}
```
**完整配置**（通过 `env` 注入运行时参数）：
```json
{
"mcpServers": {
"open-db-mcp": {
"command": "open-db-mcp",
"args": ["run"],
"env": {
"MCP_DATASOURCES_CFG_PATH": "/path/to/datasources.json",
"MCP_WHITELIST_PATH": "/path/to/whitelist.json",
"MCP_POOL_MAX": "8",
"MCP_MAX_AFFECTED_ROWS": "1000",
"MCP_QUERY_TIMEOUT_SEC": "30",
"MCP_AUDIT_LOG_PATH": "/path/to/audit.jsonl",
"DB_PASSWORD": "your_password"
}
}
}
}
```
**环境变量说明**：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `MCP_DATASOURCES_CFG_PATH` | `config/datasources.json` | 数据源配置文件路径 |
| `MCP_WHITELIST_PATH` | `config/whitelist.json` | 白名单配置文件路径 |
| `MCP_POOL_MAX` | `8` | 每个数据源的连接池上限 |
| `MCP_MAX_AFFECTED_ROWS` | `1000` | 单次 DML 允许影响的最大行数 |
| `MCP_DEFAULT_QUERY_MAX_ROWS` | `1000` | 查询默认最大返回行数 |
| `MCP_QUERY_TIMEOUT_SEC` | `30` | 查询超时（秒） |
| `MCP_AUDIT_LOG_PATH` | `~/.open-db-mcp/audit.jsonl` | 审计日志路径 |
| `MCP_AUDIT_ENABLED` | `true` | 是否启用审计日志 |
| `MCP_DM_JDBC_JAR_PATH` | `libs/DmJdbcDriver18.jar` | 达梦 JDBC 驱动 jar 路径 |
> 所有 `MCP_*` 变量也可写入 `~/.open-db-mcp/.env` 文件，效果相同。
**各客户端配置文件位置**：
| 客户端 | 配置文件 |
|--------|----------|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |
| Trae / 其他 | 参考对应客户端的 MCP 配置文档，格式相同 |
---
## 🧰 MCP 工具（25 个）
| 分类 | 工具 |
|------|------|
| 数据源管理 | `list_datasources`, `use_datasource`, `get_active_datasource`, `add_datasource`, `update_datasource`, `remove_datasource`, `ping_datasource`, `get_pool_stats`, `list_drivers` |
| 元数据浏览 | `list_schemas`, `list_tables`, `list_indexes`, `describe_table`, `explain_query`, `sample_table`, `diff_schema` |
| 查询执行 | `execute_query` |
| DML + 事务 | `execute_dml`, `execute_ddl`, `begin_transaction`, `commit_transaction`, `rollback_transaction`, `get_transaction_status` |
| 导入导出 | `export_table`, `import_csv` |
---
## 🛠️ 命令行界面
| 命令 | 说明 |
|------|------|
| `open-db-mcp init` | 引导生成配置文件 |
| `open-db-mcp doctor` | 健康检查 |
| `open-db-mcp run` | 启动 stdio MCP server |
| `open-db-mcp list` | 列出数据源与连接池状态 |
---
## 💬 联系 & 赞助
<div align="center">
<img src="image/wechat.png" alt="微信联系方式" width="220" />
<img src="image/wechat-pay.png" alt="微信打赏二维码" width="220" />
</div>
---
## 📄 License
[MIT](LICENSE) © cjp1016
