Nexus/docs/project/mysql-mcp-setup.md

MySQL MCP 配置指南

包：yclenove/mysql-mcp-server (@yclenove/mysql-mcp-server)

供 Cursor Agent 通过 MCP 安全查询 Nexus MySQL（schema、EXPLAIN、只读 SELECT）。

---

1. 安装（本机一次）

npm install -g @yclenove/mysql-mcp-server@latest

或使用项目已配置的 npx（无需全局安装，见 .cursor/mcp.json）。

验证：

npx -y @yclenove/mysql-mcp-server
# 应看到 [MySQL MCP] Starting...（Ctrl+C 退出）

---

2. 项目 MCP 配置

已提交：.cursor/mcp.json（Linux 原生：scripts/linux_mcp_mysql.sh）

不要在 mcp.json 的 env 里写密码；连接信息写在项目根 .env。

---

3. 数据库连接（.env）

方式 A：安装向导 / 已有 .env

复制示例并填写 NEXUS_DATABASE_URL 后，运行同步脚本：

copy .env.example .env
# 编辑 NEXUS_DATABASE_URL 为真实连接
python scripts/sync_mysql_mcp_env.py

脚本会根据 NEXUS_DATABASE_URL 写入：

变量	说明
MYSQL_HOST / MYSQL_PORT	从 URL 解析
MYSQL_USER / MYSQL_PASSWORD	从 URL 解析
MYSQL_DATABASE	库名（通常为 nexus）
MYSQL_READONLY	生产 true；本地开发 false（--writable）
MYSQL_DATABASE_ALLOWLIST	仅允许该库

方式 B：手动

在 .env 末尾添加与 NEXUS_DATABASE_URL 一致的 MYSQL_* 变量（见 .env.example 注释块）。

---

4. Linux 原生开发（Ubuntu / ~/Nexus）

cd ~/Nexus
python3 scripts/sync_mysql_mcp_env.py --writable
chmod +x scripts/linux_mcp_mysql.sh

.cursor/mcp.json 应使用 bash + scripts/linux_mcp_mysql.sh（不要再用 wsl + Windows 路径）。

需要 Node.js 20+：node -v 不足则 bash scripts/install_node20.sh 或 nvm install 20。

Reload Cursor MCP 后让 Agent 调用 test_connection。

本地常用命令

cd "${NEXUS_ROOT:-~/Nexus}"

python3 scripts/check_mysql.py
python3 scripts/bootstrap_database.py   # 空库建表
python3 scripts/sync_mysql_mcp_env.py --writable
bash scripts/start-dev.sh
bash scripts/local_verify.sh

---

5. （已废弃）WSL / Windows 主机

开发机已迁移 Ubuntu 原生；勿再使用 wsl MCP 或 scripts/wsl_*。历史说明见 docs/changelog/2026-06-04-cursor-plugins-linux-mcp.md。

---

6. 在 Cursor 中启用

1. 用 本仓库根目录 作为工作区打开（使 MCP 进程 cwd 能加载 .env）
2. Settings → MCP → 启用 mysql-mcp（绿点）
3. 若无显示：Developer: Reload Window
4. 测试：让 Agent 调用 test_connection 或 list_tables

验收清单可参考上游 MCP_CURSOR_TEST.md。

---

7. 安全约定

• 生产库：必须 MYSQL_READONLY=true
• 使用 MYSQL_DATABASE_ALLOWLIST 限制库名
• .env 已在 .gitignore，勿提交
• Agent 查库优先 query / describe_table / explain_query，禁止破坏性 DDL

---

8. 故障排查

现象	处理
连到 127.0.0.1 但库不对	运行 python scripts/sync_mysql_mcp_env.py 与 NEXUS_DATABASE_URL 对齐
MCP 未出现	Reload Window；确认 Node/npx 在 PATH
.env 不存在	先 copy .env.example .env 或完成 install.html
v1.4.2+ 环境被覆盖	项目根 .env 中 MYSQL_* 优先于系统环境变量
SyntaxError: Unexpected token 'with'	Node 18 过旧；bash scripts/install_node20.sh 后 Reload MCP
MCP test_connection 失败	确认 Docker MySQL 已启动：bash scripts/start-dev.sh
npx / npm ERR! ECONNRESET	配置 SOCKS5 代理，见 §9

---

9. npm/npx 代理（SOCKS5）

国内或受限网络下，npx -y @yclenove/mysql-mcp-server 可能因无法访问 registry.npmjs.org 失败。

本机代理（当前）

项	值
类型	SOCKS5
地址	192.168.124.93:10808
URL	socks5://192.168.124.93:10808

方式 A — 环境变量（终端 + MCP 脚本自动 source）

写入 scripts/npm-proxy.env（已 gitignore，从 npm-proxy.env.example 复制）：

export ALL_PROXY=socks5://192.168.124.93:10808
export HTTP_PROXY=socks5://192.168.124.93:10808
export HTTPS_PROXY=socks5://192.168.124.93:10808
export NO_PROXY=localhost,127.0.0.1,::1

scripts/linux_mcp_mysql.sh 启动时会自动 source 该文件。

注意：npm/npx 不能直接识别 socks5:// 环境变量（会报 this.connect is not a function）。

• 已本地安装 node_modules/.bin/mysql-mcp-server 时：无需 npx，MCP 正常启动。
• 需要 npx 拉包时：脚本会自动走 proxychains4（需 /etc/proxychains4.conf 含 socks5 192.168.124.93 10808）。

方式 B — npm 原生 HTTP 代理

npm 的 proxy / https-proxy 仅支持 HTTP。若网关同时提供 HTTP 端口（如 Clash 7890）：

npm config set proxy http://192.168.124.93:<HTTP端口>
npm config set https-proxy http://192.168.124.93:<HTTP端口>

查看：npm config get proxy

方式 C — proxychains（SOCKS 最可靠）

sudo apt install -y proxychains4
# 编辑 /etc/proxychains4.conf：注释掉默认 socks4，添加：
#   socks5 192.168.124.93 10808
proxychains4 -q npx -y @yclenove/mysql-mcp-server

方式 D — 本地安装，跳过 npx 联网

cd ~/Nexus
source scripts/npm-proxy.env   # 首次 install 仍需代理
npm install --no-save @yclenove/mysql-mcp-server@latest

scripts/linux_mcp_mysql.sh 应优先执行 ./node_modules/.bin/mysql-mcp-server，再回退 npx。

验证清单

• npm ping 返回 pong（非 ECONNRESET）
• timeout 3 npx -y @yclenove/mysql-mcp-server 出现 [MySQL MCP] Starting...
• Cursor Settings → MCP → mysql-mcp 绿点