Claude Code MCP サーバーが起動しない

MCP サーバーを settings.json に追加してしばらく待っても、サイドバーのツールリストに何も出てこありません。ログを見ると spawn npx ENOENT や spawn uvx ENOENT というエラーが並んでいる——このパターンに遭遇したことはないでしょうか。

個人でアプリ開発を続けてきた中で、開発環境のちょっとした設定ミスが原因で何時間も失うことがあります。2014年頃から iOS アプリをひとりで作り続けてきた経験上、「ターミナルで動くのに、別のプロセスから呼んだら動かない」というトラブルは思いのほか多く、PATH の問題はその代表格です。MCP サーバー入門の記事を書いた後にいくつかのサードパーティサーバーをローカル環境に追加しようとして、この問題に30分以上はまりました。ターミナルで npx -y @modelcontextprotocol/server-filesystem . を直接打てば問題なく動くのに、Claude Code 経由では毎回 ENOENT で弾かれる。最初はサーバー側のバグを疑いましたが、原因はまったく別のところにありました。

アーティスト（国際芸術賞17冠）と個人開発者という2つの軸を行き来する中で、テクニカルな判断は「直感」と「実測値」の両方で検証する習慣がつきました。

ENOENT は「コマンドが見つからない」という意味

ENOENT は POSIX の errno コード「Error NO ENTry（エントリが存在しない）」の略で、Node.js ではコマンドや実行ファイルが指定パスに存在しない場合にこのエラーが発生します。

spawn npx ENOENT というエラーは「npx という実行ファイルが見つからない」という意味です。あなたのターミナルでは npx が使えるのに、なぜ Claude Code からは見つからないのでしょうか？

根本原因: Claude Code は「違う PATH」で動いている

Claude Code はターミナルの子プロセスとして起動しますが、MCP サーバーの起動には child_process.spawn を使います。このとき渡される PATH は、あなたのシェルの設定ファイル（.bashrc・.zshrc）を読み込んだ後の PATH とは異なります。

特に問題になるのが次のケースです。

nvm でインストールした Node.js を使っている場合：nvm は .bashrc や .zshrc の中で PATH を動的に設定します。GUI アプリや systemd サービスとして起動した Claude Code は、このシェル設定を読み込まないため、nvm 管理下の node・npm・npx が見つかりません
Homebrew を /opt/homebrew にインストールした場合（Apple Silicon Mac）：/opt/homebrew/bin は多くのシステムデフォルト PATH に含まれていないため、同じ問題が発生します
uvx（uv）を ~/.cargo/bin や ~/.local/bin にインストールした場合：これらのディレクトリもシェル設定で後から追加されることが多く、Claude Code のスポーン時には存在しません

確認してみましょう。ターミナルで次のコマンドを打って、npx や uvx がどこにあるか調べます。

# npx の実際のパスを確認
which npx
# 出力例（nvm使用時）: /Users/masaki/.nvm/versions/node/v22.3.0/bin/npx
 
# uvx の実際のパスを確認
which uvx
# 出力例: /Users/masaki/.local/bin/uvx
 
# Claude Code が実際に使っている PATH を確認
# （Claude Code の Bash ツールで実行）
echo $PATH

ターミナルの which 結果と、Claude Code 内の echo $PATH を比べると、含まれているディレクトリが違うことが分かるはずです。

解決策1: 設定ファイルで絶対パスを使う（最も確実）

settings.json または settings.local.json でMCPサーバーを設定するとき、コマンドに絶対パスを使うのが最も確実な解決策です。

修正前（動かない設定例）:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/masaki/projects"]
    }
  }
}

修正後（絶対パスを使う）:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/masaki/.nvm/versions/node/v22.3.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/masaki/projects"]
    }
  }
}

ただし、Node.js のバージョンを切り替えると絶対パスが変わってしまうという欠点があります。nvm を使っている場合は、~/.nvm/alias/default が指すバージョンが変わると壊れます。

より安定した方法として、node_modules/.bin の実体を直接指定するか、以下の解決策2をお試しください。

解決策2: env フィールドで PATH を追加する（推奨）

settings.json には env フィールドがあり、MCP サーバーの起動環境に環境変数を追加できます。ここで PATH を上書きすることで、シェルの設定と同じように npx や uvx を見つけられるようにします。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/masaki/projects"],
      "env": {
        "PATH": "/Users/masaki/.nvm/versions/node/v22.3.0/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

現在の PATH の値は、ターミナルで echo $PATH を打てば取得できます。それをそのままコピーして env.PATH に設定するのが簡単です。

# 現在の PATH をコピー可能な形で出力
echo $PATH
# /Users/masaki/.nvm/versions/node/v22.3.0/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

この方法の利点は、nvm でバージョンを切り替えたときに対応パスだけ変えればよく、コマンド名（npx）はそのままで済む点です。

解決策3: グローバルシンボリックリンクを作る（システム全体に効く）

nvm を使っていて、毎回パスを更新するのが面倒な場合は、システムデフォルト PATH（/usr/local/bin）にシンボリックリンクを作る方法もあります。

# nvm のデフォルトバージョンのnpxへのシンボリックリンクを作成
sudo ln -sf "$(which npx)" /usr/local/bin/npx
sudo ln -sf "$(which node)" /usr/local/bin/node
 
# uvx の場合
sudo ln -sf "$(which uvx)" /usr/local/bin/uvx

ただし、nvm のバージョンを切り替えるたびにシンボリックリンクも更新が必要になります。また sudo を使うため、セキュリティポリシーによっては使えない環境もあります。

修正後の確認方法

設定を変更したら、必ず Claude Code を完全に再起動してください（ウィンドウを閉じて再度開くだけでは不十分な場合があります）。

その後、Claude Code のサイドバーやチャット欄で MCP サーバーのツールが認識されているか確認します。

# Claude Code の Bash ツールで確認（MCPサーバーが使えるかテスト）
# filesystem サーバーの例
ls /Users/masaki/projects

ツールが認識されていれば、ツール名が提案に出てくるようになります。それでもエラーが続く場合は、Claude Code MCP 接続エラー完全解決ガイドもあわせてご参照ください。

よくある組み合わせパターン

実際の環境では、以下のようなパターン別の対処を参考にしてください。

npx が見つからない（nvm使用）

# settings.json の env に追加するパス
which npx  # → /Users/masaki/.nvm/versions/node/v22.3.0/bin/npx
# 上記ディレクトリをenv.PATHの先頭に追加

uvx が見つからない

# uvx のパスを確認
which uvx  # → /Users/masaki/.local/bin/uvx または /Users/masaki/.cargo/bin/uvx
# 上記ディレクトリをenv.PATHの先頭に追加

Homebrew コマンドが見つからない（Apple Silicon）

# Homebrew のパスを確認
which brew  # → /opt/homebrew/bin/brew
# env.PATHに /opt/homebrew/bin を追加

MCP設定全体の見直しにも

この問題が発生したきっかけで、MCP サーバー全体の設定を見直してみると、他にも気づきがあるかもしれません。MCP × Claude 実践活用ガイドでは、どのMCPサーバーをどんな用途に使うかの整理から設定例まで紹介しています。

PATH の罠は地味ですが、一度理解してしまうと「なぜ動かないのか」の見当が格段につきやすくなります。環境構築系のトラブルの多くは「自分のシェルでは動くのに、別のプロセスから呼ぶと動かない」というパターンに帰着するので、この考え方を身につけておくと応用が効きます。

同じ症状で詰まっている方の同じ課題に取り組んでいる方の参考になれば幸いです。まず echo $PATH の出力をそのまま env.PATH に貼り付けるところから試してみてください。それだけで多くの場合は解決します。

Claude Code MCP サーバーが起動しない — "spawn ENOENT" エラーの原因は PATH の罠だった