MCP服务器路径修复工具

mcp-mac设置

修复通过以下方式管理节点时启动stdio MCP服务器的问题 非易失性存储器 或 fnm --适用于VS Code、Cursor、Claude Code、Claude Desktop以及任何阅读该标准的主机 {"mcpServers": { ... }} JSON配置。

问题

GUI启动的应用程序（VS Code、Cursor、Claude Desktop等）继承了它们的环境 launchd，而不是从交互式shell中。这意味着 ~/.zshrc / ~/.bash_profile 从未获得源代码，并且缺少在Node版本管理器（nvm、fnm）下安装的任何工具 PATH.

当其中一个应用程序试图生成MCP服务器时，它 exec()直接发出命令，然后返回 spawn pnpm ENOENT, command not found，或者——如果你用绝对路径“修复”了它——在升级Node后，绝对路径停止存在，就会出现无声中断。

为什么这通常很难解决

• macOS有意将GUI应用程序环境保持在最低限度，以实现可重复性。
• VS代码 MCP服务器文档 注意这一要求，但不要为版本管理器用户提供修复。
• 绝对路径 pnpm / node / npx 每次切换节点版本时都会更改(~/.nvm/versions/node/v20.x.x/bin/pnpm → ~/.nvm/versions/node/v22.x.x/bin/pnpm).
• 一次硬编码会过时。每次切换时，您都需要一个脚本来重新解析实际路径。

mcp-mac-setup 这样做：

1. 检测您的节点版本管理器（fnm、nvm或PNPM_HOME/ which 回退）。
2. 解决 绝对的 活动路径 node, npx, pnpm, npm 二进制文件。
3. 重写每一个 stdio 目标配置中的MCP服务器条目，以便：
   • command 是指向该服务器的正确二进制文件的绝对路径
   • env.PATH 用活动代码硬编码 bin/ 第一
   • env.PNPM_HOME / env.NVM_DIR / env.NVM_BIN 在相关时设置

支持的主机

任何读取的主机 {"mcpServers": { ... }} JSON。包括：

通过 --target <path> 以特定文件为目标。

快速开始

# rewrite every stdio server in the user-level mcp.json with absolute paths
pnpm dlx @kylebrodeur/mcp-mac-setup --binary auto

# verify everything matches the current Node version (CI-friendly)
pnpm dlx @kylebrodeur/mcp-mac-setup --check

# then reload the host
#   VS Code:        Cmd+Shift+P → Developer: Reload Window
#   Claude Code:    restart MCP servers
#   Cursor:         restart MCP servers

为什么 --binary auto?

不同的MCP服务器使用不同的启动器：

{
  "mcpServers": {
    "playwright":  { "command": "pnpm",   "args": ["dlx", "@playwright/mcp"] },
    "codegraph":   { "command": "npx",    "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] },
    "custom-shim": { "command": "node",   "args": ["./bin/my-mcp-server.js"] }
  }
}

--binary auto 重写每个服务器的 command 根据服务器实际使用的内容将匹配的绝对路径添加到解析的Node-bin目录下。 --binary pnpm （v1.0默认）仍然有效，并强制每个服务器通过 pnpm.

CLI选项

例子

# Fix everything in the user-level VS Code mcp.json
pnpm dlx @kylebrodeur/mcp-mac-setup --binary auto

# Fix a single server in a project-root .mcp.json
pnpm dlx @kylebrodeur/mcp-mac-setup --binary auto --server codegraph --target ./.mcp.json

# Force every server through pnpm (v1.0 behavior)
pnpm dlx @kylebrodeur/mcp-mac-setup --binary pnpm

# CI guard: fail the build if the config is stale
pnpm dlx @kylebrodeur/mcp-mac-setup --binary auto --check

# Use fnm even if both nvm and fnm are installed
pnpm dlx @kylebrodeur/mcp-mac-setup --binary auto --prefer fnm

何时重新运行

重新运行 mcp-mac-setup 之后：

• 升级你的Node版本(nvm use / fnm use)
• 切换节点版本管理器
• 添加或删除依赖于的MCP服务器 node/npx/pnpm/npm
• 将节点管理的二进制文件移动到新的绝对路径的任何更改

什么被保存下来

该脚本只重写需要更改的字段：

• ✅ 你自己写的绝对路径 （例如。 /opt/custom/binary) → 保留命令；仅 env.PATH 被注入，以便服务器可以找到自己的助手
• ✅ HTTP/SSE服务器 (type: "http" 或 type: "sse") → 完全跳过
• ✅ args 数组 → 不变（画廊“exec”→ “dlx”拼写错误修复仍然适用于 --binary pnpm)
• ✅ 用户定义的环境变量 → 保存，仅 PATH / PNPM_HOME / NVM_* 已合并到

VS代码任务

在任何项目中安装一键任务：

pnpm dlx @kylebrodeur/mcp-mac-setup --install-task

然后： Cmd+Shift+P → Tasks: Run Task → Fix MCP runtime path.

回购自己的 .vscode/tasks.json 为贡献者提供相同的任务。

检测优先级

1. fnm — ~/.local/share/fnm/aliases/default/bin/
2. 非易失性存储器 --阅读 ~/.nvm/alias/default （活动版本）
3. PNPM_主页/ which pnpm --最后手段回退（警告；路径可能不稳定）

用以下方式覆盖优先级 --prefer fnm 或 --prefer nvm.

需求

• macOS或Linux
• 节点≥18
• nvm或fnm管理您的节点安装（PNPM_HOME回退也有效）

贡献

欢迎在 github/kylebrodeur/mcp-mac安装程序.

在本地运行测试套件：

pnpm test

许可证

麻省理工学院