Content
<div align="center">
# ⚡ power-db-mcp
### 🔌 Multi-Datasource Database MCP Tool · stdio Local Edition
**Enable LLM Agents to access your databases safely and efficiently**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](#supported-databases)
**English** | [简体中文](README.md)
</div>
---
## 📖 Introduction
**power-db-mcp** is a multi-datasource database tool based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It provides **restricted and secure** query and write capabilities to LLM Agents through **stdio local process**, making it compatible with AI clients like Claude Desktop, Cursor, and Trae.
> 💡 Zero network dependency · Three-layer security protection · One-click datasource switching · Out-of-the-box
---
## ✨ Core Features
| | Feature | Description |
|---|------|------|
| 🗄️ | **Multi-driver support** | MySQL, Oracle, DM, PostgreSQL, Vastbase, openGauss, SQLite, unified `DriverAdapter` abstraction |
| 🚀 | **Zero network dependency** | stdio local process, compatible with Claude Desktop, Cursor, Trae |
| 🔄 | **Multi-datasource management** | Supports `datasources.json` or Kettle-style `jdbc.properties`, one-click datasource switching |
| 🛡️ | **Security protection** | Three-layer whitelist (read / write / ddl) + WHERE enforcement + affected row count pre-check + JSONL audit |
| 🔒 | **SQL injection defense** | SQL semantic analysis based on sqlparse + whitelist verification, double insurance |
| 📦 | **Packaging and distribution** | PyInstaller single-file executable for three platforms, no Python required for team members |
| 🔁 | **Transaction support** | `begin_transaction` / `commit` / `rollback` cross-statement transactions |
| 📤 | **Data import and export** | CSV / JSON format, supports batch import |
| 🔍 | **Schema Diff** | Cross-datasource table structure comparison, column / index-level difference detection |
| 🧩 | **Plugin-based drivers** | Based on `entry_points` driver plugin system, easy to extend |
---
## 🗄️ Supported Databases
| Database | Driver | Dependency |
|--------|--------|------|
| 🐬 MySQL | `mysql` | PyMySQL + DBUtils |
| 🔴 Oracle | `oracle` | oracledb thin mode |
| 🏮 DM | `dm` | JayDeBeApi + JPype1 + DmJdbcDriver jar (built-in packaging, automatic search) |
| 🐘 PostgreSQL | `postgres` | psycopg2-binary (optional) |
| 🌊 Vastbase | `vastbase` | psycopg2-binary (reuses postgres driver) |
| 🌿 openGauss | `opengauss` | psycopg2-binary (reuses postgres driver) |
| 📦 SQLite | `sqlite` | Python stdlib |
---
## 🚀 Quick Start
### 📥 Installation
```bash
git clone https://github.com/cjp1016/power-db-mcp.git
cd power-db-mcp
uv sync # or pip install -e '.[dev]'
uv run power-db-mcp init # generate ~/.power-db-mcp/ configuration directory
uv run power-db-mcp doctor # health check
```
### ⚙️ Configure Datasource
Edit `~/.power-db-mcp/datasources.json`:
```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
}
}
```
> 🔐 Password supports four secure reference methods: `env:`, `keyring:`, `cmd:`, see [Password Security](docs/security.md) for details.
### 🔗 Register to MCP Client
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"smart-db": {
"command": "power-db-mcp",
"args": ["run"],
"env": {
"MCP_DATASOURCES_CFG_PATH": "/path/to/your/datasources.json"
}
}
}
}
```
**Cursor** (`~/.cursor/mcp.json`): same structure as above.
---
## 🛠️ CLI Commands
| Command | Description |
|------|------|
| `power-db-mcp init` | 🎬 First run: guide to generate configuration file |
| `power-db-mcp doctor` | 🩺 Health check: parse configuration, ping each datasource |
| `power-db-mcp run` | ▶️ Start stdio MCP server (called by MCP client) |
| `power-db-mcp list` | 📋 List all datasources and connection pool status |
| `power-db-mcp package <target>` | 📦 PyInstaller packaging |
---
## 🧰 MCP Tool List (26)
| Category | Tool |
|------|------|
| 🗂️ Datasource Management | `list_data_sources`, `switch_data_source`, `add_data_source`, `update_data_source`, `remove_data_source`, `health_check`, `pool_stats`, `test_connection`, `parse_jdbc_url` |
| 🔎 Metadata Browsing | `list_schemas`, `list_tables`, `describe_table`, `list_indexes`, `explain_query`, `table_sample`, `schema_diff` |
| ⚡ Query Execution | `execute_query` |
| ✏️ DML + Transactions | `execute_dml`, `execute_ddl`, `begin_transaction`, `commit_transaction`, `rollback_transaction` |
| 📤 Data Import and Export | `export_table_csv`, `export_table_json`, `import_table_csv` |
---
## 📚 Documentation
Complete documentation in [docs/](docs/) directory, or start local documentation station:
```bash
mkdocs serve
# visit http://127.0.0.1:8000
```
| Document | Description |
|------|------|
| 🚀 [Quick Start](docs/getting-started.md) | From zero to running |
| ⚙️ [Configuration](docs/configuration.md) | Datasource / whitelist / environment variables |
| 🛡️ [Security Model](docs/security.md) | Three-layer whitelist + password security |
| 🧩 [Driver Development](docs/drivers.md) | Plugin-based driver extension guide |
| 🧰 [Tool Reference](docs/tools-reference.md) | 26 MCP tool details |
| ❓ [FAQ](docs/faq.md) | Frequently Asked Questions |
---
## 🏗️ Architecture
```
MCP Tool Layer (tools/) → Service Layer (services/) → Driver Layer (drivers/)
Thin packaging + parameter parsing Business logic + verification DB dialect adaptation
```
- ✅ Follows SOLID principles, high cohesion and low coupling
- ✅ Driver layer based on Protocol abstraction, easy to extend new databases
- ✅ Service layer pure business logic, can be independently unit tested
- ✅ Test coverage >80%
---
## 👨💻 Development
```bash
# Run tests
pytest
# Coverage
pytest --cov=power_db_mcp --cov-report=term-missing
# Code check
ruff check src/
mypy src/
```
---
## 💬 Contact Us
<div align="center">
Scan to add WeChat, note **power-db-mcp** to join discussion group:
<img src="image/wechat.png" alt="WeChat contact method" width="260" />
</div>
---
## ❤️ Support and Donate
If this project helps you, welcome to scan to invite the author for a cup of coffee ☕
<div align="center">
<img src="image/wechat-pay.png" alt="WeChat donation QR code" width="260" />
</div>
---
## 📄 License
[MIT](LICENSE) © power-db-mcp contributors
---
<div align="center">
**⚡ power-db-mcp** — Enable AI to safely converse with databases
[](https://github.com/cjp1016/power-db-mcp)
</div>
