Content
# dynamic-db-mcp-server
Dynamically registered MySQL compatible database MCP Server. Register database connections at runtime, with destructive SQL statement interception.
## Why create this?
Traditional database MCP Servers require all connection configurations to be **pre-written** into environment variables or configuration files. This is unrealistic in the following scenarios:
- There are dozens/hundreds of database instances
- Instance IPs change frequently
- You don't want to maintain a static configuration file
- AI needs to dynamically discover and connect to databases
**dynamic-db-mcp-server** flips the model: connections are registered **at runtime** through tool calls. AI provides host/port/user/password, the Server tests the connection, caches it, and returns an `instance_id` for subsequent queries.
## Features
- **Dynamic Registration** — No need to pre-configure connection lists, register arbitrary MySQL compatible databases at runtime
- **Connection Reuse** — Registered connections are cached, no duplicate handshakes
- **SQL Safety** — Read-only queries (SELECT/SHOW/WITH/EXPLAIN/DESC) are executed directly; destructive statements (DROP/DELETE/UPDATE/INSERT/ALTER/TRUNCATE) require explicit confirmation; dangerous statements (OUTFILE/DUMPFILE/LOAD_FILE/SHUTDOWN) are rejected
- **MySQL Protocol Compatible** — Suitable for MySQL, MariaDB, TDSQL, TDSQL-C, and any other databases using the MySQL wire protocol
- **Configuration without Sensitive Data** — No hard-coded credentials, all connections are provided at runtime
- **Stateless** — Connections exist in MCP process memory, restarting clears them
## Quick Start
### Installation
```bash
pip install dynamic-db-mcp-server
```
or run with `uv` / `uvx`:
```bash
uvx dynamic-db-mcp-server
```
### Configure in MCP Client
Add the following to your MCP client configuration (e.g., `opencode.jsonc`, `claude_desktop_config.json`):
```json
{
"mcpServers": {
"dynamic-db": {
"command": "uvx",
"args": ["dynamic-db-mcp-server"]
}
}
}
```
or run from source:
```json
{
"mcpServers": {
"dynamic-db": {
"command": "python",
"args": ["-m", "dynamic_db_mcp_server"]
}
}
}
```
### Usage
```
1. register_instance(name="my-db", host="10.0.0.5", port=3306, user="root", password="***")
→ {"instance_id": "my-db", "status": "connected"}
→ Connection tested and cached
2. list_instances()
→ [{"instance_id": "my-db", "host": "10.0.0.5", "port": 3306, "user": "root", "status": "connected"}]
3. execute_sql(instance_id="my-db", sql="SELECT 1")
→ {"columns": ["1"], "rows": [[1]], "row_count": 1}
4. execute_sql(instance_id="my-db", sql="DROP TABLE temp_test")
→ {"error": "Destructive operation requires confirmation", "sql_type": "DESTRUCTIVE", "statement": "DROP"}
5. execute_sql(instance_id="my-db", sql="DROP TABLE temp_test", confirm_destructive=true)
→ {"affected_rows": 0}
```
## Tool List
| Tool | Description |
|---|---|
| `register_instance` | Register database connection (tested with `SELECT 1`, cached) |
| `list_instances` | List all registered instances (passwords not returned) |
| `execute_sql` | Execute SQL. Read-only queries pass through directly; destructive queries require `confirm_destructive=true` |
| `list_databases` | List all databases on the instance |
| `list_tables` | List tables in the specified database (including row count and size) |
| `get_table_detail` | View table structure (column information + `SHOW CREATE TABLE` DDL) |
## SQL Safety Policy
| Category | Keywords | Behavior |
|---|---|---|
| **Read-only** | SELECT, SHOW, WITH, EXPLAIN, DESC, DESCRIBE | Execute directly |
| **Destructive** | DROP, TRUNCATE, DELETE, UPDATE, INSERT, ALTER, RENAME, GRANT, REVOKE, CREATE | Require `confirm_destructive=true` |
| **Dangerous** | OUTFILE, DUMPFILE, LOAD_FILE, SHUTDOWN, KILL | Rejected |
## Architecture
```
AI Agent
│
│ MCP Protocol (stdio)
▼
┌──────────────────────────────────────┐
│ dynamic-db-mcp-server │
│ │
│ FastMCP Server ──→ 6 Tools │
│ │ │
│ ConnectionManager │
│ - register / get / list │
│ - ping + automatic reconnection │
│ - per-instance threading.Lock │
│ │ │
│ SqlValidator │
│ - keyword classification │
│ - read-only / destructive / dangerous │
│ │ │
│ DbExecutor (pymysql) │
│ - execute / list / schema │
└──────────────────────────────────────┘
│
│ TCP 3306
▼
MySQL / MariaDB / TDSQL / TDSQL-C
```
## License
MIT
