Power Db Mcp

⚡ power-db-mcp

🔌 多数据源数据库 MCP 工具 · stdio 本地版

让 LLM Agent 安全、高效地访问你的数据库

[](https://opensource.org/licenses/MIT) [](https://www.python.org/) [](https://modelcontextprotocol.io) [](#-支持的数据库)

简体中文 | [English](README_EN.md)

---

📖 简介

power-db-mcp 是一个基于 Model Context Protocol (MCP) 的多数据源数据库工具，通过 stdio 本地进程与 Claude Desktop / Cursor / Trae 等 AI 客户端即插即用，向 LLM Agent 暴露受限且安全的查询与写入能力。

> 💡 零网络依赖 · 三层安全护栏 · 一键切换数据源 · 开箱即用

---

✨ 核心特性

| | 特性 | 说明 | |---|------|------| | 🗄️ | 多驱动支持 | MySQL、Oracle、达梦（DM）、PostgreSQL、Vastbase、openGauss、SQLite，统一 DriverAdapter 抽象 | | 🚀 | 零网络依赖 | stdio 本地进程，与 Claude Desktop / Cursor / Trae 即插即用 | | 🔄 | 多数据源管理 | 支持 datasources.json 或 Kettle 风格 jdbc.properties，一键切换数据源 | | 🛡️ | 安全护栏 | 三层白名单（read / write / ddl）+ WHERE 强制 + 影响行数预检 + JSONL 审计 | | 🔒 | SQL 注入防御 | 基于 sqlparse 的 SQL 语义分析 + 白名单校验，双保险 | | 📦 | 可打包分发 | PyInstaller 三平台单文件可执行，团队成员无需装 Python | | 🔁 | 事务支持 | begin_transaction / commit / rollback 跨语句事务 | | 📤 | 数据导入导出 | CSV / JSON 格式，支持批量导入 | | 🔍 | Schema Diff | 跨数据源表结构对比，列 / 索引级差异检测 | | 🧩 | 插件化驱动 | 基于 entry_points 的驱动插件体系，易于扩展 |

---

🗄️ 支持的数据库

| 数据库 | Driver | 依赖 | |--------|--------|------| | 🐬 MySQL | mysql | PyMySQL + DBUtils | | 🔴 Oracle | oracle | oracledb thin 模式 | | 🏮 达梦 DM | dm | JayDeBeApi + JPype1 + DmJdbcDriver jar（内置打包，自动搜索） | | 🐘 PostgreSQL | postgres | psycopg2-binary（可选） | | 🌊 海量数据库 Vastbase | vastbase | psycopg2-binary（复用 postgres 驱动） | | 🌿 openGauss | opengauss | psycopg2-binary（复用 postgres 驱动） | | 📦 SQLite | sqlite | Python stdlib |

---

🚀 快速开始

📥 安装

git clone https://github.com/cjp1016/power-db-mcp.git
cd power-db-mcp
uv sync                  # 或 pip install -e '.[dev]'
uv run power-db-mcp init # 生成 ~/.power-db-mcp/ 配置目录
uv run power-db-mcp doctor  # 健康检查

⚙️ 配置数据源

编辑 ~/.power-db-mcp/datasources.json：

{
  "LOCAL_MYSQL": {
    "driver": "com.mysql.cj.jdbc.Driver",
    "url": "jdbc:mysql://127.0.0.1:3306/test_db?characterEncoding=utf8mb4",
    "user": "root",
    "password": "env:DB_PASSWORD",
    "pool_min": 2,
    "pool_max": 4
  }
}

> 🔐 密码支持 env: / keyring: / cmd: 四种安全引用方式，详见 [密码安全](docs/security.md)。

🔗 注册到 MCP 客户端

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "smart-db": {
      "command": "power-db-mcp",
      "args": ["run"],
      "env": {
        "MCP_DATASOURCES_CFG_PATH": "/path/to/your/datasources.json"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json）：同上结构。

---

🛠️ CLI 命令

| 命令 | 说明 | |------|------| | power-db-mcp init | 🎬 首次运行：引导生成配置文件 | | power-db-mcp doctor | 🩺 健康检查：解析配置、ping 每个数据源 | | power-db-mcp run | ▶️ 启动 stdio MCP server（被 MCP 客户端调用） | | power-db-mcp list | 📋 列出所有数据源与连接池状态 | | power-db-mcp package | 📦 PyInstaller 打包 |

---

🧰 MCP 工具清单（26 个）

| 分类 | 工具 | |------|------| | 🗂️ 数据源管理 | list_data_sources, switch_data_source, add_data_source, update_data_source, remove_data_source, health_check, pool_stats, test_connection, parse_jdbc_url | | 🔎 元数据浏览 | list_schemas, list_tables, describe_table, list_indexes, explain_query, table_sample, schema_diff | | ⚡ 查询执行 | execute_query | | ✏️ DML + 事务 | execute_dml, execute_ddl, begin_transaction, commit_transaction, rollback_transaction | | 📤 数据导入导出 | export_table_csv, export_table_json, import_table_csv |

---

📚 文档

完整文档见 [docs/](docs/) 目录，或启动本地文档站：

mkdocs serve
# 访问 http://127.0.0.1:8000

| 文档 | 说明 | |------|------| | 🚀 [快速开始](docs/getting-started.md) | 从零到跑通 | | ⚙️ [配置说明](docs/configuration.md) | 数据源 / 白名单 / 环境变量 | | 🛡️ [安全模型](docs/security.md) | 三层白名单 + 密码安全 | | 🧩 [驱动开发](docs/drivers.md) | 插件化驱动扩展指南 | | 🧰 [工具参考](docs/tools-reference.md) | 26 个 MCP 工具详解 | | ❓ [FAQ](docs/faq.md) | 常见问题 |

---

🏗️ 架构

MCP 工具层（tools/）  →  服务层（services/）  →  驱动层（drivers/）
    薄包装 + 参数解析        业务逻辑 + 校验         DB 方言适配

• ✅ 遵循 SOLID 原则，高内聚低耦合
• ✅ 驱动层基于 Protocol 抽象，易于扩展新数据库
• ✅ 服务层纯业务逻辑，可独立单元测试
• ✅ 测试覆盖率 >80%

---

👨‍💻 开发

# 运行测试
pytest

# 覆盖率
pytest --cov=power_db_mcp --cov-report=term-missing

# 代码检查
ruff check src/
mypy src/

---

💬 联系我们

扫码添加微信，备注 power-db-mcp 加入交流群：

---

❤️ 支持赞助

如果这个项目对你有帮助，欢迎扫码请作者喝杯咖啡 ☕

---

📄 License

[MIT](LICENSE) © power-db-mcp contributors

---

⚡ power-db-mcp — 让 AI 与数据库安全对话

[](https://github.com/cjp1016/power-db-mcp)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cjp1016
• Source: cjp1016/power-db-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.