mysql-mcp

使用 mcp-server-mysql 查询与操作 MySQL

前置检查

本 skill 只适用于已连接 mcp-server-mysql 的会话。动手前先确认当前工具列表里确实存在 mysql_query 等 mysql_* 工具（客户端里通常带 mcp__<server名>__ 前缀，按后缀识别）。如果没有这些工具：本 skill 不适用，不要凭本文档虚构调用它们——按常规方式完成数据库任务（如本地 mysql CLI），或建议用户按仓库 README 配置连接本 MCP 后再来。

这个 MCP server 是安全优先设计：每条 SQL 先过工业级 AST 解析校验（解析失败一律拒绝），读语句包在只读事务里执行，驱动层禁多语句。理解它的边界，你就能高效使用它；试图绕过只会浪费轮次。

心智模型

• 默认只读、白名单默认全拒。能执行什么语句类型（allowed_statements）、能碰哪些表（table_whitelist）完全由服务端配置决定，会话内无法更改。
• DENIED 是边界，不是故障。收到 DENIED [规则名]: 原因 时，按下文对照表调整做法；同一条语句换个写法重试大概率还是拒（校验基于语义解析，注释、大小写、版本化注释 /*!...*/ 都藏不住东西）。
• fail-closed。极个别 MySQL 边缘语法解析器不认时也会被拒（parse_error），这时换等价写法，而不是反复重试原句。
• 需要放宽边界（加白名单、开写权限、调行数上限）时，如实告诉用户去改服务端 config.yaml 并重启 MCP，不要在 SQL 层想办法。

工具选择

任务	工具
单条读查询（SELECT / SHOW / DESCRIBE / EXPLAIN）	mysql_query
单条写语句（INSERT / UPDATE / DELETE / DDL，需服务端开启）	mysql_execute
多条语句原子执行（全成或全回滚）	mysql_script
看有哪些表可用	mysql_list_tables
看某张表的列结构	mysql_describe_table
分析单条 SELECT 的执行计划	mysql_explain
本会话执行统计（哪条最慢、拒了几条）	mysql_stats

硬规则（违反必被拒）

1. 一次一条语句。mysql_query / mysql_execute 只接受单语句；多条语句唯一的入口是 mysql_script。
2. 读写分道。写语句走 mysql_query 会被 wrong_tool 拒，反之亦然。选工具本身就是意图声明。
3. UPDATE / DELETE 必须带 WHERE（block_unfiltered_writes 默认开启）。这是防误操作护栏：若用户确实要全表操作，先向用户确认，再用能表达真实意图的条件（如主键范围）执行，不要默默加 WHERE 1=1 规避。
4. 脚本内禁 DDL。MySQL 的 DDL 会隐式提交事务，破坏"全成或全回滚"承诺，所以 mysql_script 无条件拒 DDL——即使服务端开了 ddl 权限。DDL 单独用 mysql_execute 执行。
5. 这些语句在任何工具里都不可用：SET、USE、GRANT、CALL、LOAD DATA、LOCK TABLES、BEGIN / COMMIT / ROLLBACK 等事务控制。跨库查询用 库名.表名 限定，不要 USE；需要事务用 mysql_script，不要手写 BEGIN/COMMIT。
6. SELECT ... INTO OUTFILE / LOAD_FILE() 被永久禁止，没有开关，不要尝试。
7. 只能访问白名单内的表。JOIN、子查询、CTE、INSERT ... SELECT 里涉及的每一张表都会被逐一校验，任何一张不在白名单整条拒。

推荐工作流

探索陌生库

先 mysql_list_tables（只显示白名单内的表，这就是你的全部可用面），再对目标表 mysql_describe_table，然后小步查询。不要跳过这两步直接猜表名——猜错的每一次都是 table_whitelist 拒绝。

读查询

• 返回行数有硬上限（默认 1000），超限会截断并标注。统计问题用 COUNT / GROUP BY 等聚合，不要拉全表数行数。
• 探索性查询主动带 LIMIT，既快又省上下文。
• 查询有超时（默认 30s），大查询先用 mysql_explain 看看代价。