dynamic-db-mcp-server 0.1.0

Dynamic MySQL-compatible database MCP server - register connections at runtime, execute SQL with destructive statement interception

dynamic-db-mcp-server

动态注册的 MySQL 兼容数据库 MCP Server. 运行时注册数据库连接, 执行 SQL 时自带破坏性语句拦截.

为什么造这个轮子

传统的数据库 MCP Server 要求把所有连接配置事先写进环境变量或配置文件. 这在以下场景不现实:

• 有几十/上百个数据库实例
• 实例 IP 经常变动
• 不想维护一份静态配置文件
• 需要 AI 动态发现并连接数据库

dynamic-db-mcp-server 翻转了模型: 连接在运行时通过工具调用注册. AI 提供 host/port/user/password, Server 测试连接, 缓存它, 返回 instance_id 供后续查询使用.

特性

• 动态注册 — 无需预配置连接列表, 运行时注册任意 MySQL 兼容数据库
• 连接复用 — 注册的连接会被缓存, 不重复握手
• SQL 安全 — 只读查询 (SELECT/SHOW/WITH/EXPLAIN/DESC) 直接执行; 破坏性语句 (DROP/DELETE/UPDATE/INSERT/ALTER/TRUNCATE) 需显式确认; 危险语句 (OUTFILE/DUMPFILE/LOAD_FILE/SHUTDOWN) 一律拒绝
• MySQL 协议兼容 — 适用于 MySQL, MariaDB, TDSQL, TDSQL-C 等任何使用 MySQL 线协议的数据库
• 配置无敏感数据 — 无硬编码凭据, 所有连接均为运行时提供
• 无状态 — 连接存在于 MCP 进程内存中, 重启即清空

快速开始

安装

pip install dynamic-db-mcp-server

或通过 uv / uvx 运行:

uvx dynamic-db-mcp-server

在 MCP 客户端中配置

在你的 MCP 客户端配置中添加 (如 opencode.jsonc, claude_desktop_config.json):

{
  "mcpServers": {
    "dynamic-db": {
      "command": "uvx",
      "args": ["dynamic-db-mcp-server"]
    }
  }
}

或从源码运行:

{
  "mcpServers": {
    "dynamic-db": {
      "command": "python",
      "args": ["-m", "dynamic_db_mcp_server"]
    }
  }
}

使用流程

1. register_instance(name="my-db", host="10.0.0.5", port=3306, user="root", password="***")
   → {"instance_id": "my-db", "status": "connected"}
   → 连接已测试并缓存

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}

工具列表

工具	说明
register_instance	注册数据库连接 (用 SELECT 1 测试, 缓存)
list_instances	列出所有已注册实例 (不返回密码)
execute_sql	执行 SQL. 只读直接通过, 破坏性需 confirm_destructive=true
list_databases	列出实例上的所有数据库
list_tables	列出指定库的表 (含行数和大小)
get_table_detail	查看表结构 (列信息 + SHOW CREATE TABLE DDL)

SQL 安全策略

类别	关键字	行为
只读	SELECT, SHOW, WITH, EXPLAIN, DESC, DESCRIBE	直接执行
破坏性	DROP, TRUNCATE, DELETE, UPDATE, INSERT, ALTER, RENAME, GRANT, REVOKE, CREATE	需 confirm_destructive=true
危险	OUTFILE, DUMPFILE, LOAD_FILE, SHUTDOWN, KILL	一律拒绝

架构

AI Agent
   │
   │  MCP 协议 (stdio)
   ▼
┌──────────────────────────────────────┐
│      dynamic-db-mcp-server           │
│                                      │
│  FastMCP Server ──→ 6 个工具         │
│       │                              │
│  ConnectionManager                   │
│   - register / get / list            │
│   - ping + 自动重连                   │
│   - per-instance threading.Lock      │
│       │                              │
│  SqlValidator                        │
│   - 关键字分类                        │
│   - 只读 / 破坏性 / 危险              │
│       │                              │
│  DbExecutor (pymysql)                │
│   - execute / list / schema          │
└──────────────────────────────────────┘
               │
               │  TCP 3306
               ▼
    MySQL / MariaDB / TDSQL / TDSQL-C

License

MIT