MCP サーバの典型エラーをトラブルシュート

切り分けプレイブック

「MCP サーバが繋がらない」報告のほとんどは 5 つのカテゴリのどれかに収まります。順番にチェックすればカテゴリを 1 つずつ除外できます。

1. JSON 構文エラー

設定が不正なら、クライアントは静かに MCP を無効化します。検証するには：

# macOS / Linux
python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

または JSON フォーマッター に貼り付けると、失敗箇所をハイライトしてくれます。よくある原因：末尾カンマ、エスケープ漏れバックスラッシュ（Windows パス 参照）、Markdown コピペ由来のスマートクオート。

2. spawn の ENOENT（'npx' not found）

クライアント環境の PATH にバイナリがありません。確認：

which npx    # macOS / Linux
where.exe npx   # Windows

ターミナルでは動くが GUI クライアントで動かない場合、シェル rc ファイル読み込み前に GUI アプリが起動しています。対処：

• 公式インストーラから Node を入れ直す（システム全体 PATH）。
• command に絶対パスを書く："command": "/usr/local/bin/npx"。

3. env 変数の欠落・誤り

[error] BRAVE_API_KEY is not set

サーバ別ログで正確な変数名を確認し、設定にコピーしてください。タイポすると派手に失敗します。

「正しそうなのに 401」の場合：

• GitHub: GitHub トークン で再発行。fine-grained トークンはデフォルトで期限があります。
• Brave: キーが BSA_ 始まりで、月次クォータ内であることを確認。

4. パスの問題

filesystem の場合、パスが存在し、クライアント実行ユーザから読めることを確認：

ls -la /Users/you/Documents

シンボリックリンクやネットワークマウントなら実体パスに置き換えてください。

5. 接続後のサイレントクラッシュ

サーバは初期化に成功するが、モデルがツールを呼ぶと終了する。ログをテール：

tail -F ~/Library/Logs/Claude/mcp-server-*.log

通常スタックトレースが現れます。npm 配布のサーバなら GitHub Issues を確認 — 新しいバージョンが古いクライアントで動かない（あるいは逆）場合があります。既知の動作バージョンに固定：

"args": ["-y", "@modelcontextprotocol/server-github@2024.10.7"]

最終手段：最小構成

何もうまくいかないときは、設定を「/tmp を指す filesystem サーバ 1 つ」だけにして読み込めるか確認します。それすら失敗するなら、問題は環境（PATH、権限、JSON パース）であってサーバ個別の問題ではありません。