Content
<div align="center">
# Tool List
**Enable LLM Agent to access your database securely**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
**English** | [English](README_EN.md)
</div>
---
A multi-data source database tool based on [MCP Protocol](https://modelcontextprotocol.io), which can be used with AI clients like Claude Desktop, Cursor, and Trae.
**Supported Databases**: MySQL · Oracle · DM · PostgreSQL · Vastbase · openGauss · SQLite
**Core Capabilities**:
- Multi-data source switching with one click
- Three-layer whitelist security protection
- Pre-check of affected rows
- Transaction support
- CSV/JSON import and export
- Cross-database Schema Diff
- Plugin-based driver extension
---
## 🚀 Quick Start
```bash
git clone https://github.com/cjp1016/open-db-mcp.git
cd open-db-mcp
uv sync # Install dependencies
uv run open-db-mcp init # Generate ~/.open-db-mcp/ configuration
uv run open-db-mcp doctor # Health check
```
### Configure Data Sources
Edit `~/.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`: Abbreviation (`mysql` / `oracle` / `dm` / `postgres` / `sqlite`) or full JDBC class name
- `password`: Supports plain text or secure reference (`env:variable_name` / `keyring:` / `cmd:`)
- Optional parameters: `pool_min`, `pool_max`, `max_affected_rows`
### Register to MCP Client
**Simplified Configuration** (using default path `config/datasources.json`):
```json
{
"mcpServers": {
"open-db-mcp": {
"command": "open-db-mcp",
"args": ["run"]
}
}
}
```
**Complete Configuration** (injecting runtime parameters via `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"
}
}
}
}
```
**Environment Variable Description**:
| Variable | Default Value | Description |
|------|--------|------|
| `MCP_DATASOURCES_CFG_PATH` | `config/datasources.json` | Data source configuration file path |
| `MCP_WHITELIST_PATH` | `config/whitelist.json` | Whitelist configuration file path |
| `MCP_POOL_MAX` | `8` | Maximum connection pool size for each data source |
| `MCP_MAX_AFFECTED_ROWS` | `1000` | Maximum affected rows for a single DML operation |
| `MCP_DEFAULT_QUERY_MAX_ROWS` | `1000` | Default maximum rows returned for a query |
| `MCP_QUERY_TIMEOUT_SEC` | `30` | Query timeout in seconds |
| `MCP_AUDIT_LOG_PATH` | `~/.open-db-mcp/audit.jsonl` | Audit log path |
| `MCP_AUDIT_ENABLED` | `true` | Enable audit log |
| `MCP_DM_JDBC_JAR_PATH` | `libs/DmJdbcDriver18.jar` | DM JDBC driver jar path |
> All `MCP_*` variables can also be written to `~/.open-db-mcp/.env` file with the same effect.
**Client Configuration File Locations**:
| Client | Configuration File |
|--------|----------|
| 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 / Others | Refer to the corresponding client's MCP configuration documentation, same format |
---
## 🧰 MCP Tools (25)
| Category | Tools |
|------|------|
| Data Source Management | `list_datasources`, `use_datasource`, `get_active_datasource`, `add_datasource`, `update_datasource`, `remove_datasource`, `ping_datasource`, `get_pool_stats`, `list_drivers` |
| Metadata Browsing | `list_schemas`, `list_tables`, `list_indexes`, `describe_table`, `explain_query`, `sample_table`, `diff_schema` |
| Query Execution | `execute_query` |
| DML + Transaction | `execute_dml`, `execute_ddl`, `begin_transaction`, `commit_transaction`, `rollback_transaction`, `get_transaction_status` |
| Import/Export | `export_table`, `import_csv` |
---
## 🛠️ CLI
| Command | Description |
|------|------|
| `open-db-mcp init` | Guided configuration generation |
| `open-db-mcp doctor` | Health check |
| `open-db-mcp run` | Start stdio MCP server |
| `open-db-mcp list` | List data sources and connection pool status |
---
## 💬 Contact & Sponsor
<div align="center">
<img src="image/wechat.png" alt="WeChat contact" width="220" />
<img src="image/wechat-pay.png" alt="WeChat donation QR code" width="220" />
</div>
---
## 📄 License
[MIT](LICENSE) © cjp1016
