Claude Code MCPサーバー接続失敗の原因と設定ファイルの読み方

Claude Code に MCP サーバーを設定したのに接続できない――そのとき確認すべきことは、難解なログを解読する前に「設定ファイルが正しく書けているか」です。この記事では settings.json の構造・記述ミスのパターン・診断の手順を順番に解説します。

MCPサーバーの設定ファイルはどこにあるか

Claude Code の MCP サーバー設定は settings.json に書きます。ファイルの置き場所は2か所あり、適用スコープが異なります。

公式ドキュメントによると、両方が存在する場合はプロジェクトローカルの設定が優先されます（一部の権限ポリシーを除く）。まず「どちらのファイルに書いたか」を確認してください。

# グローバル設定を確認する
cat ~/.claude/settings.json

# プロジェクトローカルを確認する
cat .claude/settings.json

ファイル自体が存在しない場合、Claude Code は起動時に空の設定として扱います。設定を書いたつもりでパスが間違っていた、というケースは意外と多いです。

settings.json の構造と各フィールドの意味

MCP サーバーの設定は mcpServers キーの下にサーバー名をキーとして記述します。

{
  "mcpServers": {
    "my-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

各フィールドの意味を整理します。

type を省略すると stdio として扱われます。stdio の場合、Claude Code がコマンドを子プロセスとして起動し、stdin/stdout 経由でプロトコル通信します。すでに別プロセスで動いている HTTP サーバーに接続したい場合は sse を使います。

{
  "mcpServers": {
    "my-api-server": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}

よくある接続失敗のパターン4つ

パターン1：JSON の構文エラー

最もよくあるミスです。JSON は末尾カンマを許容しないため、次のような書き方はパースエラーになります。

❌ 末尾カンマ（構文エラー）

{
  "mcpServers": {
    "server-a": { "command": "npx", "args": [] },
  }
}

✅ 正しい

{
  "mcpServers": {
    "server-a": { "command": "npx", "args": [] }
  }
}

ほかにも「ダブルクォートの代わりにシングルクォートを使う」「閉じ括弧が足りない」「文字列中のバックスラッシュが未エスケープ」なども頻出します。Claude Code は JSON のパースに失敗すると mcpServers 全体を無視する可能性があるため、ミスが1か所でも設定が全スキップになる場合があります。

パターン2：コマンドが見つからない

command に npx や node を書いても、Claude Code が起動するシェルに PATH が通っていない場合があります。nvm・fnm・volta などで Node.js をインストールしている環境では特に注意が必要です。Claude Code はログインシェルとは別のプロセスとして起動するため、.bashrc や .zshrc の PATH 設定が読み込まれないことがあります（環境によって異なります）。

パターン3：サーバープロセスが即座にクラッシュ

コマンドは見つかっても、サーバーが起動直後に終了するケースです。主な原因は次のとおりです。

• 依存パッケージが未インストール
• 必要な環境変数（APIキーなど）が env フィールドに未設定
• args で指定したディレクトリやファイルが存在しない

パターン4：タイムアウト

サーバーの初期化が規定時間内に完了しない場合も接続失敗として扱われます。起動時にネットワーク接続や大量のファイル読み込みを行う実装だと発生しやすい問題です。

接続失敗を診断する手順

手順1：JSON の構文を確認する

jq がインストール済みであれば次のコマンドで構文チェックできます。

jq . ~/.claude/settings.json && echo "OK"

jq がない場合は Python でも確認できます。

python3 -m json.tool ~/.claude/settings.json

エラーが出た場合は行番号の周辺を確認して修正してください。エラーがなければ OK と表示されます。

手順2：登録済みサーバーを一覧する

claude mcp list

設定したサーバー名が表示されない場合、ファイルが読み込めていないか JSON 構文エラーがある可能性が高いです。ファイルパスを再確認してください。

手順3：コマンドをターミナルで手動実行する

settings.json に書いた command と args をそのままターミナルで実行し、プロセスが起動するか確認します。

# filesystem サーバーを手動で起動する例
npx -y @modelcontextprotocol/server-filesystem /tmp

エラーなく起動して待機状態になれば、コマンド自体に問題はありません。command not found が出た場合は PATH の問題です。

手順4：PATH の問題はフルパスで解決する

which コマンドでフルパスを確認し、command に記述します。

which node
# 例: /home/yourname/.nvm/versions/node/v22.0.0/bin/node

which npx
# 例: /home/yourname/.nvm/versions/node/v22.0.0/bin/npx

{
  "mcpServers": {
    "my-server": {
      "command": "/home/yourname/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

または env フィールドで PATH を補完する方法もあります。

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "PATH": "/home/yourname/.nvm/versions/node/v22.0.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

環境によってパスは異なるため、which コマンドの出力で必ず確認してください。

手順5：設定変更後は Claude Code を再起動する

settings.json を編集した後は、Claude Code を完全に終了して再起動する必要があります。同じセッション内で設定ファイルを書き換えても反映されません（執筆時点の動作）。

Claude Code のインタラクティブセッション内では /mcp コマンドで接続中のサーバーとツール一覧を確認できます。接続に成功していれば、ここにサーバー名とツール名が表示されます。

まとめ

Claude Code の MCP 接続失敗は、多くの場合、次の3点のどれかが原因として考えられます。

まず jq . ~/.claude/settings.json を実行してください。多くの場合は原因の特定につながります。設定が正しく読み込まれているかは claude mcp list で確認し、最終的に /mcp コマンドで接続済みのツールを確認する流れが確実です。