soul-yongping/开发文档/8、部署/Soul-MySQL-MCP配置说明.md

Soul-MySQL MCP 配置说明

配置文件: C:\Users\29195\.cursor\mcp.json

---

为什么之前无法执行？

原因 1：连接时没有带端口

• 之前用 --host、--port 分开传参，部分 MCP 客户端在运行时调用 connect_db 时只传 host/user/password/database，不传 port。
• 你的数据库在 14413，MySQL 默认是 3306，所以实际连的是错误端口 → 容易 ETIMEDOUT 或连不上。
• 所以会出现「无法执行」或执行报错。

原因 2：改用「连接串」才能带上端口

• @f4ww4z/mcp-mysql-server 支持用一条连接串启动，格式里可以写清楚端口：
  • mysql://用户:密码@主机:端口/数据库名
• 这样 MCP 启动时就会用 14413 去连，不会再用默认 3306。

---

当前正确配置（连接串方式）

在 mcp.json 里 Soul-MySQL 应类似：

"Soul-MySQL": {
  "command": "npx",
  "args": [
    "-y",
    "@f4ww4z/mcp-mysql-server",
    "mysql://cdb_outerroot:Zhiqun1984@56b4c23f6853c.gz.cdb.myqcloud.com:14413/soul_miniprogram"
  ],
  "env": {}
}

含义：

• 用户: cdb_outerroot
• 密码: Zhiqun1984
• 主机: 56b4c23f6853c.gz.cdb.myqcloud.com
• 端口: 14413（写在连接串里）
• 数据库: soul_miniprogram

这样 MCP 会按 主机:14413 连接，不再用 3306。

---

使用前必做：重启 Cursor

1. 完全退出 Cursor（关掉所有窗口）。
2. 再重新打开 Cursor。
3. 等 MCP 列表里 Soul-MySQL 显示为已连接/可用。

否则会继续用旧配置（不带端口），仍然无法执行。

---

若仍无法执行，可排查这些

1. 本机网络/防火墙

• 数据库在腾讯云，若你本机或公司网络不允许访问外网 14413，连接会超时。
• 解决：在能访问该库的机器上跑 Cursor（或先做 SSH 隧道，把 14413 转到本机 3306，再在 mcp.json 里连 localhost:3306）。

2. 腾讯云白名单

• 腾讯云 MySQL 有「来源 IP 白名单」。
• 你当前上网的 公网 IP 必须在白名单里，否则会被拒绝。
• 解决：在腾讯云控制台 → 该 MySQL 实例 → 白名单里加上你当前的公网 IP。

3. 密码含特殊字符

• 若以后改了密码，且密码里有 @、#、/ 等，需要做 URL 编码 再写进连接串，否则连接串会被解析错。

---

小结

• 无法执行 多半是：连库时没带端口 14413 或网络/白名单不通。
• 已把 Soul-MySQL 改成带端口的连接串配置，并写进 mcp.json。
• 修改后务必重启 Cursor 再试；若仍不行，按上面「若仍无法执行」逐项排查。