Skip to content

lisuki9/DBridge

BranchesTags

Repository files navigation

DBridge

让 AI 安全地查询你的数据库

License: MIT Node.js Version Platform MCP

English | 日本語 | 한국어 | 简体中文

📖 简介

DBridge 是一个跨平台的数据库 MCP (Model Context Protocol) 配置管理工具。它在 AI 助手（Claude、Kiro、Codex 等）和数据库之间建立了一道安全屏障，确保 AI 只能执行只读查询，无法修改或删除任何数据。

目前支持的数据库类型：

  • MySQL / MariaDB
  • PostgreSQL
  • SQLite（MCP 侧使用 better-sqlite3，需本机可用）
  • MongoDB

为什么需要它？

当你想让 AI 助手帮你查询数据库时，直接给它数据库密码是非常危险的。DBridge 提供了：

  • 4 层安全防护 - 从数据库层到结果层的全方位保护
  • AST 级别 SQL 验证 - 比正则表达式更可靠的安全检查
  • 加密密码存储 - AES-256-GCM 加密，密码不再明文存储
  • 一键配置导出 - 轻松集成到各种 AI 工具

✨ 功能特性

功能 描述
🔒 安全的密码存储 使用 AES-256-GCM 加密存储数据库密码
🛡️ AST 级别 SQL 验证 基于语法树的只读 SQL 验证，比正则更安全
📁 配置组管理 按环境（dev/staging/prod）组织数据库连接
🚀 多平台导出 一键生成 Kiro、Claude Desktop、Codex 配置
💻 跨平台支持 支持 macOS、Windows、Linux
🖥️ 桌面应用 提供 Electron GUI 界面（可选）
📊 SQL 教练 查询优化建议和执行计划分析

🚀 快速开始

前置要求

  • Node.js >= 18
  • MySQL / MariaDB / PostgreSQL / SQLite / MongoDB（按需）

安装

# 克隆项目
git clone https://github.com/lisuki9/DBridge.git
cd DBridge

# 安装依赖（本仓库使用 npm workspaces，推荐在根目录执行）
npm install

# 构建 Node 端（CLI + MCP Server）
npm run build:node

# （可选）构建 Electron 桌面端
npm run build:electron

基本使用

cd node

# 1. 添加数据库连接
node dist/cli.js connection add \
  --name dev-mysql \
  --host 127.0.0.1 \
  --port 3306 \
  --user root \
  --password your-password \
  --database mydb

# 2. 创建配置组
node dist/cli.js profile add \
  --name dev \
  --description "开发环境" \
  --connections dev-mysql \
  --default dev-mysql

# 3. 导出配置到 AI 工具
node dist/cli.js export kiro dev      # Kiro
node dist/cli.js export claude dev    # Claude Desktop
node dist/cli.js export codex dev     # Codex

🔧 配置方式

方式一：CLI 命令行（推荐）

使用 SQLite 数据库存储配置，密码加密存储：

# 连接管理
node dist/cli.js connection list              # 列出所有连接
node dist/cli.js connection add -n name ...   # 添加连接
node dist/cli.js connection show <name>       # 查看连接详情
node dist/cli.js connection remove <name>     # 删除连接

# 配置组管理
node dist/cli.js profile list                 # 列出所有配置组
node dist/cli.js profile add -n name ...      # 创建配置组
node dist/cli.js profile show <name>          # 查看配置组详情
node dist/cli.js profile remove <name>        # 删除配置组

# 导出配置
node dist/cli.js export kiro <profile>        # 导出 Kiro 配置
node dist/cli.js export claude <profile>      # 导出 Claude Desktop 配置
node dist/cli.js export codex <profile>       # 导出 Codex 配置

方式二：环境变量

# 单连接配置
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=password
export MYSQL_DATABASE=testdb

方式三：JSON 配置文件

export MYSQL_CONNECTIONS_FILE=/path/to/connections.json
查看 JSON 配置示例 
{
  "connections": {
    "dev-mysql": {
      "host": "127.0.0.1",
      "port": 3306,
      "user": "readonly_user",
      "password": "password",
      "database": "mydb"
    }
  },
  "default": "dev-mysql"
}

配置存储位置

平台 路径
macOS ~/Library/Application Support/DBridge/
Windows %APPDATA%\DBridge\
Linux ~/.config/dbridge/

Electron 桌面端支持在「设置 -> 存储」里自定义配置存储目录；选择后会实际影响 config.db / master.key 的读取与写入、导出文件路径，以及 MCP 服务启动时写入的 MCP_CONFIG_DB / MCP_MASTER_KEY_FILE。切换目录时会在新目录缺少文件的情况下复制旧的 config.db / master.key（不会删除旧目录内容）。

🤖 AI 工具集成

Kiro

node dist/cli.js export kiro dev
# 将输出添加到项目的 .kiro/mcp.json

Claude Desktop

node dist/cli.js export claude dev
# 将配置合并到：
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json

Codex

node dist/cli.js export codex dev
# 将配置合并到 ~/.codex/config.toml

MCP 工具列表

集成后，AI 可以使用以下工具：

工具 功能
mysql_list_connections 列出所有连接
mysql_list_schemas 列出数据库
mysql_list_tables 列出表和视图
mysql_describe_table 查看表结构
mysql_query 执行只读查询
mysql_query_page 分页查询
mysql_explain_json 查询执行计划分析

说明：

  • 一个配置组（profile）只能包含一种数据库类型（例如不能把 MySQL 和 PostgreSQL 连接放在同一个 profile 中），因为单个 MCP Server 实例是“单方言”的。
  • 对于 MySQL/MariaDB/PostgreSQL/SQLite，为了兼容历史工具名，仍使用 mysql_* 工具名，但实际会根据 profile 的数据库类型执行对应查询。
  • 对于 MongoDB，提供单独的 mongo_* 工具：
    • mongo_list_connections / mongo_list_databases / mongo_list_collections
    • mongo_find / mongo_aggregate（只读，禁止 $out/$merge 等写操作）

🖥️ Electron 桌面应用

提供可视化界面管理连接和配置。

# 在仓库根目录运行（推荐）
npm run dev:electron   # 开发模式
npm run build:electron # 生产构建

功能

  • 连接管理 - 添加、编辑、删除、测试数据库连接
  • 配置组管理 - 创建环境配置组，关联连接
  • 配置导出 - 选择平台，预览并导出配置
  • MCP 服务管理 - 启动/停止服务，查看实时日志
  • SQL 教练 - 查询优化建议

打包发布

npm run dist:mac    # macOS
npm run dist:win    # Windows
npm run dist:linux  # Linux

🔒 安全机制

4 层防护

┌─────────────────────────────────────────────────────────┐
│  Layer 1: 数据库层 - 使用只读权限账户（最重要）           │
├─────────────────────────────────────────────────────────┤
│  Layer 2: 会话层 - SET SESSION TRANSACTION READ ONLY    │
├─────────────────────────────────────────────────────────┤
│  Layer 3: 查询层 - AST 级别 SQL 验证                     │
├─────────────────────────────────────────────────────────┤
│  Layer 4: 结果层 - 限制返回行数（默认 200 行）           │
└─────────────────────────────────────────────────────────┘

允许的操作

✅ SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (CTE)

禁止的操作

❌ INSERT, UPDATE, DELETE, REPLACE ❌ CREATE, ALTER, DROP, TRUNCATE ❌ GRANT, REVOKE ❌ LOCK, FOR UPDATE ❌ INTO OUTFILE, LOAD DATA

密码加密

  • 算法：AES-256-GCM
  • 密钥派生：scrypt
  • 每次加密使用随机 IV

❓ 常见问题

连接数据库失败

症状：Error: connect ECONNREFUSED 或 Access denied

解决方案：

  1. 检查数据库服务是否运行
  2. 确认主机、端口、用户名、密码正确
  3. 检查防火墙是否允许连接
  4. 确认用户有远程连接权限： 
    GRANT SELECT ON database.* TO 'user'@'%';
FLUSH PRIVILEGES;
SQL 查询被拒绝

症状：Query rejected: Only read-only queries are allowed

解决方案：

  • 这是安全机制正常工作
  • 只允许 SELECT、SHOW、DESCRIBE、EXPLAIN、WITH 语句
  • 不支持任何写操作
MCP 服务器启动失败

解决方案：

  1. 检查 Node.js 版本 >= 18
  2. 确认配置文件路径正确
  3. 手动测试启动： 
    cd node && node dist/index.js
密码解密失败

解决方案：

  1. 可能是数据库文件损坏，尝试重新添加连接
  2. 检查数据目录权限
  3. 如果问题持续，删除数据目录重新配置
查询结果被截断

解决方案：

  • 这是安全限制，默认最多返回 200 行
  • 使用 mysql_query_page 工具进行分页查询
  • 可通过环境变量调整：MYSQL_MAX_RESULT_ROWS=500
Windows 上 better-sqlite3 安装失败

解决方案：

  1. 安装 Visual Studio Build Tools
  2. 或使用：npm install -g windows-build-tools
  3. 重新安装依赖

📁 项目结构

dbridge/
├── node/                    # Node.js MCP 服务器
│   ├── src/
│   │   ├── index.ts        # MCP 服务器入口
│   │   ├── cli.ts          # CLI 命令行工具
│   │   ├── sql/            # SQL 验证模块
│   │   └── storage/        # 存储模块
│   └── tests/              # 单元测试
├── electron/               # Electron 桌面应用
│   ├── src/
│   │   ├── main/          # 主进程
│   │   ├── preload/       # Preload 脚本
│   │   └── renderer/      # 渲染进程 (React)
│   └── dist/              # 编译输出
└── docs/                   # 文档

🧪 开发脚本

以下命令均在仓库根目录运行：

npm run typecheck   # TypeScript 严格类型检查（node + electron）
npm run lint        # ESLint
npm run format      # Prettier 格式化
npm test            # Node 端单测
npm run build       # 构建 node + electron

🔧 环境变量

变量名 说明 默认值
MCP_CONFIG_DB SQLite 数据库路径 系统默认路径
MCP_PROFILE 配置组名称 -
MCP_MASTER_KEY_FILE 主密钥文件路径 系统默认路径
MYSQL_HOST MySQL 主机 127.0.0.1
MYSQL_PORT MySQL 端口 3306
MYSQL_USER MySQL 用户名 -
MYSQL_PASSWORD MySQL 密码 -
MYSQL_DATABASE 默认数据库 -
MYSQL_MAX_RESULT_ROWS 最大返回行数 200

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

如果这个项目对你有帮助，请给一个 ⭐ Star！

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages