Codex Release Bot
5.9 KiB
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 中启用
- 用 本仓库根目录 作为工作区打开（使 MCP 进程
cwd能加载.env） - Settings → MCP → 启用
mysql-mcp（绿点） - 若无显示：Developer: Reload Window
- 测试：让 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绿点