mysql-mcp-pro

mysql-mcp-pro

🇺🇸 点击此处查看英文版

一个生产级的 MySQL MCP Server，让 AI 助手（Claude Desktop / WorkBuddy / Cursor / Cline 等）通过标准化协议安全高效地操作 MySQL 数据库。

✨ 为什么选 mysql-mcp-pro？

相比社区其他 MySQL MCP 实现，本项目提供了更完整的能力集：

特性	mysql-mcp-pro	其他 MCP
连接池（减少握手开销）	✅	❌
事务支持（begin/commit/rollback）	✅	❌
EXPLAIN 自动解读	✅	❌
结果导出 CSV/JSON（Excel 友好 BOM）	✅	❌
ER 关系图数据（nodes/edges）	✅	少数
视图 / 存储过程 / 函数 / 触发器 浏览	✅	少数
查询历史 & 审计日志	✅	❌
MCP Prompts 模板（生成/优化/对比/概览）	✅	❌
安全分级（只读/DDL/危险语句/超时/行限/参数化）	✅	基础
多传输模式（stdio / SSE / streamable-http）	✅	部分

🚀 快速开始

1. 安装

# 从源码（推荐先 clone 再使用）
git clone https://github.com/CCCT173/mysql-mcp-pro.git
cd mysql-mcp-pro
pip install -e .

# 或从 PyPI（待发布）
pip install mysql-mcp-pro

2. 配置环境变量

复制 .env.example 为 .env 并编辑：

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

READ_ONLY=false         # 只读模式
ALLOW_DDL=false          # 是否允许 CREATE/ALTER/DROP
MAX_RESULT_ROWS=1000     # 单次查询最大返回行数
QUERY_TIMEOUT=30         # 查询超时(秒)

POOL_SIZE=5
AUDIT_LOG=true           # 审计日志
EXPORT_DIR=./exports     # 导出目录

3. 在你的 MCP 客户端注册

WorkBuddy

编辑 ~/.workbuddy/mcp.json：

{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "D:/path/to/mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

或者如果你已经 pip install -e .：

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-pro",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "READ_ONLY": "true"
      }
    }
  }
}

Cursor / Cline

在项目根目录创建 .cursor/mcp.json（Cursor）或在 Cline 设置中添加，格式同上。

工具

MCP 注册平台（Smithery、mcp.so、glama 等）会自动提取工具信息。

• ping — 测试 MySQL 连接；返回服务器版本和连接池统计信息。
• get_server_status — MySQL 关键状态指标（连接数、QPS、慢查询、InnoDB 行数、流量）。
• list_databases — 列出所有数据库（系统数据库与用户数据库）。
• list_tables — 列出表及其引擎、行数、大小和注释。可选参数 database。
• describe_table — 显示表结构：列、主键、索引、外键、CREATE SQL。参数：table（必填）、database（可选）。
• list_views — 列出数据库中的视图。
• list_routines — 列出存储过程或函数。参数：routine_type（PROCEDURE/FUNCTION）、database。
• list_triggers — 列出数据库中的触发器。
• er_graph — 将跨表外键关系表示为节点和边，可用于生成 ER 图。
• execute_query — 执行任意 SQL（读/写/DDL，带安全防护），支持参数化。参数：sql、database、params、session_id。
• execute_select — 执行只读 SELECT/SHOW/DESCRIBE/EXPLAIN，并提供额外安全保护。参数：sql、database、params、limit。
• get_table_data — 快速分页获取表数据。参数：table、columns、where、order_by、limit、offset。
• count_rows — 统计表中的行数，可选 WHERE 条件。参数：table、database、where。
• explain_query — 对查询执行 EXPLAIN 并返回通俗易懂的性能分析。参数：sql、database、params、format。
• export_query — 将 SELECT 结果导出为 CSV（UTF-8 BOM，适用于 Excel）或 JSON 文件。参数：sql、filename、format（csv/json）、database、params。
• list_query_history — 查看此会话中最近执行的 SQL（耗时、行数、错误）。参数：limit。
• begin_transaction — 开启新事务；返回用于后续调用的 session_id。参数：database。
• commit_transaction — 提交未完成的事务。参数：session_id。
• rollback_transaction — 回滚未完成的事务。参数：session_id。
• show_processlist — 显示当前 MySQL 进程列表（SHOW FULL PROCESSLIST）。
• kill_query — 终止 MySQL 进程（需要 SUPER 权限）。参数：process_id。

🛠 工具一览（25 个）

连接 & 状态

• ping — 测试连接、返回服务器版本与连接池状态
• get_server_status — MySQL 关键指标（连接数、QPS、慢查询、流量等）

元数据浏览

• list_databases — 列出所有数据库（区分系统库 / 用户库）
• list_tables — 列出表，含引擎、行数、大小、注释
• describe_table — 表结构：字段、主键、索引、外键、建表 SQL
• list_views — 列出视图
• list_routines — 列出存储过程 / 函数
• list_triggers — 列出触发器
• er_graph — 跨表外键关系（nodes + edges），便于画 ER 图

查询执行

• execute_query — 执行任意 SQL（读/写/DDL，受安全策略约束），支持参数化
• execute_select — 只读 SELECT 专用（即使配置错误也只允许读）
• get_table_data — 快速取数：columns / where / order_by / limit / offset
• count_rows — 统计行数（支持可选 WHERE）

分析 & 导出

• explain_query — EXPLAIN 执行计划 + 中文性能洞察
• export_query — 结果导出 CSV（UTF-8 BOM，Excel 友好）或 JSON 文件
• list_query_history — 本会话 SQL 历史（耗时 / 行数 / 错误）

事务

• begin_transaction — 开启事务，返回 session_id
• commit_transaction — 提交事务
• rollback_transaction — 回滚事务

监控 & 管理

• show_processlist — 当前 MySQL 进程列表
• kill_query — Kill 指定进程（需要 SUPER 权限）

MCP Resources（4 个）

• mysql://databases — 数据库列表
• mysql://tables/{database} — 表列表
• mysql://schema/{database}/{table} — 表结构
• mysql://er/{database} — ER 关系图数据

MCP Prompts（4 个模板）

• generate_query — 根据自然语言和表信息生成 SQL
• optimize_sql — 分析并优化现有 SQL 性能
• compare_schema — 对比两张表的结构差异
• database_summary — 数据库整体概览报告

🔒 安全模型

危险语句（GRANT/REVOKE/SHUTDOWN/KILL/FLUSH/RESET）→ 永远禁止
DDL（CREATE/ALTER/DROP/RENAME/TRUNCATE）            → 由 ALLOW_DDL 控制
写操作（INSERT/UPDATE/DELETE）                       → 由 READ_ONLY 控制
读操作（SELECT/SHOW/DESCRIBE/EXPLAIN）               → 永远允许

• 参数化查询 %s 占位符，杜绝 SQL 注入
• 结果集默认 1000 行上限，防止意外返回海量数据
• 服务端 MAX_EXECUTION_TIME 强制查询超时
• 所有执行 SQL 落盘到 exports/audit.log

📁 项目结构

mysql-mcp-pro/
├── server.py              # MCP 服务器（连接池 / 事务 / 导出 / 审计）
├── pyproject.toml         # 包元数据，入口 mysql-mcp-pro
├── .env.example           # 环境变量模板
├── LICENSE                # MIT
├── README.md / README.en.md
└── scripts/
    ├── setup_test_db.py   # 创建 mcp_test 样例数据库
    ├── test_v2.py         # 53 项回归测试
    └── diag.py            # MySQL 握手包诊断工具

🧪 本地测试

# 1. 创建样例数据库（mcp_test，users + orders 表，带外键）
python scripts/setup_test_db.py

# 2. 跑全量回归测试
python scripts/test_v2.py
# → 53 passed, 0 failed

🤝 贡献

欢迎提 issue 和 PR！请确保：

1. 新功能带测试用例
2. 现有测试全部通过
3. 遵循现有代码风格

📄 License

MIT