🐛
Claude Desktop で npx / bunx が見つからない問題の解決法
TL;DR
Claude Desktop の MCP サーバー設定で npx や bunx が「command not found」になる問題は、launchd の PATH に含まれるディレクトリへシンボリックリンクを作成することで解決できる。フルパス指定は不要。
# これだけでOK
sudo ln -sf ~/.bun/bin/bunx /usr/local/bin/bunx
問題の概要
Claude Desktop で MCP サーバーを設定する際、以下のような設定が動作しないケースがある。
{
"mcpServers": {
"filesystem": {
"command": "bunx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}
}
}
ログを確認すると、こんなエラーが出ている。
[error] [filesystem] spawn bunx ENOENT
ターミナルでは bunx が普通に使えるのに、Claude Desktop からは見つからない。
原因
macOS の GUI アプリはシェルの PATH を継承しない
Claude Desktop は launchd 経由で起動される macOS アプリケーション。そのため、~/.zshrc や ~/.bashrc で設定した PATH 環境変数を読み込まない。
ターミナル起動
→ シェル初期化
→ ~/.zshrc 読み込み
→ PATH に ~/.bun/bin 追加
→ bunx が使える
Claude Desktop 起動
→ launchd 経由
→ 最小限の環境変数のみ
→ bunx が見つからない
確認方法
# launchd が認識している PATH
launchctl getenv PATH
# シェルの PATH
echo $PATH
多くの場合、launchd の PATH には ~/.bun/bin や nvm / mise などで管理しているパスが含まれていない。
解決策: シンボリックリンクを作成
launchd の PATH に含まれるディレクトリへシンボリックリンクを作成するのが最もシンプル。多くの環境では /usr/local/bin が含まれるが、含まれない場合もあるので、先に launchctl getenv PATH で確認しておく。
bun / bunx の場合
sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
sudo ln -sf ~/.bun/bin/bunx /usr/local/bin/bunx
mise 管理の node / npm / npx の場合
方法A: 特定バージョンを直接リンク
sudo ln -sf ~/.local/share/mise/installs/node/24.13.0/bin/node /usr/local/bin/node
sudo ln -sf ~/.local/share/mise/installs/node/24.13.0/bin/npm /usr/local/bin/npm
sudo ln -sf ~/.local/share/mise/installs/node/24.13.0/bin/npx /usr/local/bin/npx
方法B: mise の shims 経由（バージョン変更に自動追従）
sudo ln -sf ~/.local/share/mise/shims/node /usr/local/bin/node
sudo ln -sf ~/.local/share/mise/shims/npm /usr/local/bin/npm
sudo ln -sf ~/.local/share/mise/shims/npx /usr/local/bin/npx
注意点
- bun をアンインストールした場合、シンボリックリンクが壊れる（削除すれば OK）
- mise で直接バージョン指定した場合、バージョン変更時に再リンクが必要
まとめ
シンボリックリンク方式のメリットは以下の通り。
-
設定ファイルがクリーン:
claude_desktop_config.jsonにフルパスや/bin/sh経由の記述が不要 - 一度設定すれば完了: MCP サーバーを追加するたびに対応する必要がない
- 開発環境への影響なし: 既存のターミナルや VSCode の動作は変わらない
バージョン管理ツール（mise など）を使っている場合は、shims 経由でリンクすることでバージョン変更にも自動追従できる。
ぜひ試してみてください。
𝕏フォローしてくれると嬉しいです
𝕏でも情報発信しているので、フォローしていただけると励みになります！
Discussion