【エラー別完全解説】Claude Code MCPサーバーが接続できない時の完全解決ガイド

最近、「Claude Code」でMCPサーバーを接続しようとして、「Failed to connect」や「MCP error -32000」といったエラーに悩まされている方が増えているようですね！どうやら、MCPサーバーの接続エラーは環境変数の設定漏れやポート競合など、いくつかの典型的な原因に集約されるようです。

そこで今回は、実際のエラーメッセージをもとに、「Claude Code」のMCPサーバー接続エラーの切り分けと復旧を行ってみました！パターンごとにコマンドをそのままコピーして使えるようにまとめていますので、ぜひ皆さんも記事を読んで試してみてください！

この記事で分かること

Claude CodeのMCPサーバー接続エラーが起きる仕組みとclaude mcp listの読み方
環境変数未設定・EADDRINUSE・認証トークン期限切れ・プロセスクラッシュ・タイムアウトそれぞれの具体的な解決コマンド
settings.jsonの正しい書き方と、複数MCPサーバーを併用する際の競合回避設計

MCPサーバー接続の仕組みとエラーが起きる箇所

Claude CodeがMCPサーバーに接続できない場合、まず「どの通信方式で、どこで失敗しているか」を理解することが復旧の第一歩になります。Claude CodeのMCPサーバーはstdio方式とHTTP/SSE方式の2種類があり、それぞれエラーの出方が異なります。

Claude CodeのMCPサーバー接続でできること

ローカルプロセスをstdio（標準入出力）経由で子プロセスとして起動し、JSON-RPCで通信する
リモートのHTTP/SSEエンドポイントに接続し、認証トークン付きでツールを呼び出す
claude mcp listやclaude --mcp-debugで接続状態と失敗地点をリアルタイムに可視化する

ここで、stdio方式とHTTP方式ではMCPサーバー接続エラーの原因がどう違うのかという疑問が出てくると思います。

大きな差としては、「stdio方式はClaude Codeがプロセスを直接起動するため環境変数やパスの問題が起きやすく、HTTP方式はネットワークやポート、認証トークンの問題が起きやすい」という点です。これにより、エラーメッセージから通信方式を逆算し、原因を早く絞り込むことが出来ます。

今話題の、「MCP error -32000 / -32001」というやつですね！

比較すると、以下のようになります。

項目	stdio方式	HTTP/SSE方式
通信の仕組み	Claude Codeが子プロセスを起動し標準入出力でJSON-RPCをやり取り	URL経由でHTTPリクエスト/SSEストリームを送受信
典型的な接続エラー	spawn ENOENT、Client Closed、-32000 Connection closed	Connection refused、EADDRINUSE、-32001 Request timed out
主な原因	コマンドパス不正、依存モジュール未インストール、stdout汚染	ポート競合、認証トークン期限切れ、プロキシによるSSEバッファリング

「MCPサーバーの接続エラーって原因が多くて難しそう…」と感じるかもしれませんが、この記事を読めば初心者の方でも大丈夫！順を追ってエラーメッセージ別の具体的な解決コマンドまで解説します。

stdio方式の通信フロー

Claude Codeがsettings.jsonまたは.mcp.jsonに記載されたcommandとargsを使い、子プロセスをspawnします。子プロセスの標準出力（stdout）がJSON-RPCの通信チャネルとして使われるため、そこにログ出力（console.log等）が混入すると通信が破損し、MCPサーバー接続エラーとして表面化します。

HTTP/SSE方式の通信フロー

Claude CodeはURLに対してHTTPリクエストを送信し、サーバー側はServer-Sent Eventsで応答を返します。ここではポート番号の競合、リバースプロキシによるバッファリング、OAuthトークンの有効期限切れがMCPサーバーの接続エラーの主因になります。

エラーメッセージ別・MCPサーバー接続エラーの対処法

状態確認：claude mcp listの見方

Claude CodeのMCPサーバー接続状態はclaude mcp listで確認します。正常時と異常時で出力が明確に異なります。

# ファイル名: check_mcp_status.sh
claude mcp list

正常な出力例（すべて接続済み）

github          ✓ Connected
filesystem      ✓ Connected
sentry          ✓ Connected

異常な出力例（複数のパターンが混在）

github          ✗ Failed to connect
filesystem      ! Connected · tools fetch failed
sentry          ! Needs authentication
db-server       ✗ Connection error

「Failed to connect」はプロセス起動失敗、「tools fetch failed」は接続はできたがツール一覧取得に失敗、「Needs authentication」は認証待ちの状態を示します。以降はエラーメッセージ別に、原因と解決コマンドをセットで解説します。

1. 環境変数未設定エラー

実際のエラー出力例

Error: Missing required environment variable GITHUB_TOKEN
MCP server "github" tools fetch failed: 401 Unauthorized

原因：MCPサーバーはClaude Codeによって最小限の環境で起動されるため、シェルの.zshrcや.env に書いた変数は継承されません。settings.jsonのenvブロックに明示的に書かないと、MCPサーバー接続エラーとして401/403が返ります。

解決コマンド全文

# ファイル名: fix_env.sh
claude mcp remove github
claude mcp add github --env GITHUB_TOKEN=ghp_your_token_here -- npx -y @modelcontextprotocol/server-github

再確認手順：claude mcp listで対象サーバーが✓ Connectedになっているか確認し、続けてclaude mcp get githubでenvブロックに変数が反映されているかを確認します。

2. EADDRINUSEポート競合エラー

実際のエラー出力例

Error: listen EADDRINUSE: address already in use :::3000
MCP server "local-http" failed to connect

原因：HTTP方式のMCPサーバーが指定ポートで待受を試みますが、別プロセスが同じポートを既に使用しているため接続エラーになります。

解決コマンド全文

# ファイル名: fix_port_conflict.sh
# macOS/Linuxで占有プロセスを特定
lsof -i :3000
# 該当PIDを終了
kill -9 <PID>
# それでも競合する場合はポートを変更してサーバーを再登録
claude mcp remove local-http
claude mcp add --transport http local-http http://localhost:3001

再確認手順：lsof -i :3001で新ポートが空いていることを確認後、claude mcp listで✓ Connectedになるかチェックします。

3. 認証トークン期限切れエラー

実際のエラー出力例

Authentication failed (401)
OAuth token has expired
does not meet scope requirement user:profile

原因：Claude CodeはOAuthトークンをキャッシュしており、長時間セッションや久しぶりの起動でトークンの有効期限が切れると、以降のツール呼び出しがすべて401で失敗するMCPサーバー接続エラーになります。

解決コマンド全文

# ファイル名: fix_auth_expired.sh
/logout
/login
# それでも401が続く場合はキャッシュを完全削除
rm -rf ~/.claude/auth
claude
/login

再確認手順：ログイン後にclaude mcp listで対象サーバーの状態を確認し、Claude Code内で/mcpを実行して再接続をトリガーします。

4. サーバープロセスクラッシュ

実際のエラー出力例

MCP error -32000: Connection closed
Client Closed
spawn npx ENOENT

原因：Claude Codeは実行環境が最小化されているため、PATHに依存したnpxやnodeの相対パス指定が解決できず、子プロセスが起動直後に落ちてMCPサーバー接続エラーになります。stdoutへのconsole.log混入も同様の症状を引き起こします。

解決コマンド全文

# ファイル名: fix_process_crash.sh
which node
which npx

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/server/index.js"],
      "env": { "MY_API_KEY": "your-key-here" }
    }
  }
}

Node.jsサーバー側のログ出力もstderrに変更します。

// 修正前：stdoutを汚染しJSON-RPCを破壊する
console.log("Server started");
// 修正後：安全にstderrへ出力
console.error("Server started");

再確認手順：コマンドを直接ターミナルで実行してクラッシュしないか確認し、node /absolute/path/to/server/index.jsのように単独起動が成功したらClaude Codeを再起動してclaude mcp listで確認します。

5. タイムアウトエラー

実際のエラー出力例

MCP error -32001: Request timed out
Message from client: {"method":"notifications/cancelled","params":{"reason":"Error: MCP error -32001: Request timed out"}}

原因：サーバープロセスは起動しconnectionは開始されますが、初期化リクエスト（initialize）に規定時間内で応答できず、MCPサーバー接続エラーになります。SSE接続をnginx等がバッファリングしている場合に多発します。

解決コマンド全文

# ファイル名: fix_timeout.sh
curl -N https://your-server.example.com/sse
export MCP_TIMEOUT=60000
export API_TIMEOUT_MS=900000
claude

nginx等のリバースプロキシを使う場合はバッファリングを無効化します。

# ファイル名: nginx_sse.conf
location /mcp/ {
    proxy_pass http://your-backend;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding on;
}

再確認手順：curl -Nでストリームが即座に流れてくるか確認し、Claude Code内で/mcpを実行して再接続、claude mcp listで✓ Connectedになるかチェックします。

settings.jsonの書き方とデバッグ・競合回避の実践

settings.jsonでのMCPサーバー定義

MCPサーバー接続エラーの多くはsettings.json（または.mcp.json）の記述ミスに起因します。正しいstdio方式とHTTP方式の定義は以下の通りです。

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"],
      "env": {}
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

よくある記述ミスは次の3例です。1つ目はcommandに相対パス（node、npx）をそのまま書いてしまい実行環境でPATHが解決できないケース。2つ目はenvブロックを省略し、シェルの環境変数に依存してしまうケース。3つ目はJSON末尾のカンマ抜けや余分なカンマによって設定ファイル全体がパースエラーとなり、全てのMCPサーバーが認識されなくなるケースです。

# ファイル名: validate_json.sh
cat ~/.claude.json | python3 -m json.tool

デバッグ用のログ確認手順

MCPサーバー接続エラーの原因特定にはclaude --mcp-debugフラグが有効です。すべての通信メッセージと失敗地点が表示されます。

# ファイル名: debug_mcp.sh
claude --mcp-debug
tail -f ~/Library/Logs/Claude/mcp-server-SERVERNAME.log

ログに「Server stderr: ...started」という文言だけが出ている場合は起動確認メッセージであり、実際は正常動作している場合があります。一方「Connection failed: spawn npx ENOENT」のように具体的なエラー内容が出ていれば、それが本当のMCPサーバー接続エラーの原因です。

複数MCPサーバー併用時の競合回避設計

複数のMCPサーバーを同時に登録すると、起動順序やタイムアウト値の違いによって一部だけが接続エラーになることがあります。優先度の高いサーバーを先に安定させ、重いサーバー（npxでパッケージをダウンロードするものなど）にはタイムアウトを長めに設定します。

# ファイル名: adjust_timeout_per_server.sh
export MCP_TIMEOUT=60000
export API_TIMEOUT_MS=900000
export CLAUDE_CODE_MAX_RETRIES=5

ポートを使うHTTP方式のサーバーを複数併用する場合は、事前にlsof -i :PORTでポートの空き状況を確認し、サーバーごとに異なるポートを割り当てることでEADDRINUSEによるMCPサーバー接続エラーを未然に防げます。

接続後のツール動作確認

設定変更後はClaude Code内で/mcpを実行し、再接続と各MCPサーバーのツール一覧取得を確認します。

# ファイル名: recheck_after_fix.sh
claude mcp get <server-name>

ツール一覧が空の場合はサーバー側の環境変数不足や設定ミスが残っている可能性が高いため、該当サーバーのenvブロックを再確認してください。

まとめ：Claude Code MCPサーバー接続エラーは切り分けが9割

今回は、Claude CodeのMCPサーバー接続エラーをエラーメッセージ別に切り分け、復旧する作業に挑戦してみました。

公式ドキュメントを読むだけでも大まかな方向性は分かりますが、「Claude Code」のMCPサーバー接続エラーはclaude mcp listとclaude --mcp-debugを併用すれば、原因の8〜9割は自力で特定できるため、これは使わないのはもったいない！と感じました。

導入も簡単ですので、みなさんも今回の記事を参考に、ぜひ「Claude Code」のMCPサーバー接続エラーのトラブルシューティングを実践してみてください！

【エラー別完全解説】Claude Code MCPサーバーが接続できない時の完全解決ガイド｜エラーメッセージ別対処法一覧

MCPサーバー接続の仕組みとエラーが起きる箇所

stdio方式の通信フロー

HTTP/SSE方式の通信フロー

エラーメッセージ別・MCPサーバー接続エラーの対処法

状態確認：claude mcp listの見方

1. 環境変数未設定エラー

2. EADDRINUSEポート競合エラー

3. 認証トークン期限切れエラー

4. サーバープロセスクラッシュ

5. タイムアウトエラー

settings.jsonの書き方とデバッグ・競合回避の実践

settings.jsonでのMCPサーバー定義

デバッグ用のログ確認手順

複数MCPサーバー併用時の競合回避設計

接続後のツール動作確認

まとめ：Claude Code MCPサーバー接続エラーは切り分けが9割

関連記事