昨日まで問題なく動いていたMCPサーバーが、今朝起動したら突然「接続できない」「ツールが見つからない」と表示される――こういった状況は、Claude Code を日常的に使っているとかならず一度は経験します。私自身、複数のMCPサーバーを並行運用していたとき、あるアップデートをきっかけに全部まとめて動かなくなり、丸半日を診断に費やしたことがあります。
問題は「どこから調べればいいかわからない」という点です。MCPサーバーの不具合には、設定ファイルのJSON構文エラーから、認証トークンの期限切れ、Claude Code 自体のバージョン変更まで、原因がさまざまな層に渡ります。その原因を効率的に絞り込むための5ステップ診断を順番にご紹介します。
ステップ1：まず /mcp コマンドでサーバーの状態を確認する
Claude Code のターミナルで /mcp と入力すると、現在設定されているMCPサーバーの接続状態が一覧で表示されます。
/mcp
表示される状態は主に3種類です：
- connected：正常に接続されています
- connecting：接続を試みている途中です（しばらく待って再確認）
- failed：接続に失敗しています（これが問題の対象）
failed と表示されているサーバーが特定できたら、次のステップに進みます。複数のサーバーがすべて failed になっている場合は、ステップ5（Claude Code 再起動）を先に試すのが早道です。
ステップ2：stderrログで具体的なエラーメッセージを読む
MCPサーバーが failed になっているとき、最も手がかりになるのが stderr（標準エラー出力） のログです。Claude Code はMCPサーバーのプロセスを起動したとき、そのstderrをキャプチャして内部ログに記録しています。
Claude Code の stderr ログ確認機能について詳しくはこちら
ログを確認する方法は以下の通りです：
# macOS / Linux の場合
cat ~/.claude/logs/mcp-*.log 2>/dev/null | tail -100
# または Claude Code のデバッグモードで起動
claude --debugデバッグモードで起動すると、MCPサーバーの起動・接続・エラーメッセージがリアルタイムで流れてきます。以下のようなキーワードが出ていれば、それが原因です：
ENOENT：実行ファイルが見つからない（パスの問題）ECONNREFUSED：ポートに接続できない（サーバーが起動していない）401 Unauthorized：認証トークンが無効SyntaxError：設定ファイルのJSON構文エラーMODULE_NOT_FOUND：Node.jsモジュールが見つからない（npm install未実行）
ステップ3：設定ファイルの構文エラーをチェックする
MCPサーバーの設定は ~/.claude/claude_desktop_config.json（Claudeアプリ）または ~/.claude.json（Claude Code CLI）に記述されています。JSON は1つのカンマや括弧のミスで全体が壊れるため、編集後に確認が必要です。
# JSON構文チェック（jq コマンドを使用）
cat ~/.claude.json | jq . > /dev/null && echo "✅ JSON構文OK" || echo "❌ 構文エラーあり"
# Claudeアプリの設定ファイルをチェック
cat ~/.claude/claude_desktop_config.json | jq . > /dev/null && echo "✅ OK" || echo "❌ エラー"構文エラーがある場合、jq は「どの行の何文字目か」を教えてくれます。エラーが出た行の前後を確認して、余分なカンマや引用符の欠落を直してください。
よくある構文ミスのパターン：
// ❌ 最後の要素にカンマが残っている（末尾カンマ）
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"], // ← ここのカンマが不要
}
}
}
// ✅ 正しい形式
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"]
}
}
}ステップ4：認証・環境変数の問題を確認する
APIキーやOAuthトークンを使うMCPサーバー（GitHubのMCPサーバーなど）は、トークンの期限切れや環境変数の取り込みに失敗するケースがあります。
# 環境変数が正しく設定されているか確認
echo $GITHUB_TOKEN
echo $ANTHROPIC_API_KEY
# シェル設定ファイルに記述されているか確認
grep -n "GITHUB_TOKEN\|ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc 2>/dev/null環境変数が空の場合、MCPサーバーは起動しても認証エラーで機能しません。また、Claude Code は起動時にシェル設定を読み込まない場合があるため、設定ファイルに env フィールドを使って明示的に渡す方法が安定しています：
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}ただし、設定ファイルにトークンを直接書くのはセキュリティリスクがあります。本番環境では Claude Code の環境変数管理 の記事を参考に、適切な管理方法を採用してください。
ステップ5：Claude Code とMCPサーバーを再起動する
「設定は正しいはずなのに動かない」というとき、単純な再起動で解決することが意外と多いです。MCPサーバーの接続はセッションに紐づいているため、長時間起動したままにしているとゾンビプロセスが溜まり、新しい接続を受け付けられなくなることがあります。
# Claude Code を完全に終了して再起動
# 1. Claude Code のターミナルで Ctrl+C（または q でセッション終了）
# 2. プロセスが残っていないか確認
ps aux | grep claude | grep -v grep
# 3. 残っていれば強制終了
pkill -f "claude" 2>/dev/null
# 4. 再起動
claude再起動後、/mcp コマンドで接続状態を再確認してください。
よくある原因とすぐ使える対処コマンド
診断をより速くするために、よくある原因と対処を整理しました。
Node.jsモジュールが見つからない（MODULE_NOT_FOUND）
MCPサーバーのディレクトリで npm install を実行し忘れている場合です。
cd /path/to/your/mcp-server
npm installnpxコマンドのキャッシュが古い
@modelcontextprotocol/server-* 系のパッケージをnpxで使っている場合、キャッシュが古いバージョンを参照していることがあります。
# npxキャッシュをクリア
npx clear-npx-cache 2>/dev/null || npm cache clean --forceポートが他のプロセスに占有されている
HTTPベースのMCPサーバーを使っている場合、ポートが競合していることがあります。
# ポート3000が使用中か確認
lsof -i :3000
# 使用中のプロセスを終了
kill $(lsof -ti :3000)診断できない場合の最終手段
上記の5ステップを試しても解決しない場合は、MCP設定を一時的に空にしてから1つずつ追加することをおすすめします。どのサーバーが競合しているかを切り分けるためです。
詳細なMCP接続の高度なトラブルシューティングは、Claude Code MCP 上級トラブルシューティングの記事が参考になります。
MCPサーバーの不具合は一見複雑に見えますが、ほとんどのケースは「設定ファイルの構文エラー」「環境変数の未設定」「プロセスの競合」のどれかです。まずはstderrログのエラーメッセージを確認することから始めてください。それだけで、原因の80%は特定できます。