MCP サーバのデバッグ：クライアントログの読み方

ログの保存場所

各クライアントは MCP デバッグログをアプリ本体ログとは別に書き出します：

• Claude Desktop（macOS）：~/Library/Logs/Claude/mcp.log に加え、サーバごとに mcp-server-filesystem.log 等のファイル。
• Claude Desktop（Windows）：%APPDATA%\Claude\logs\mcp.log。
• Cursor：View → Output パネル → ドロップダウンで MCP を選択。
• Cline：Output → Cline ドロップダウン → "MCP" で検索。

確認すべきこと

正常なサーバはクライアント起動直後に "Initialized" を出力します。よくある失敗パターン：

[error] Failed to spawn server "github": ENOENT

command 値を解決できませんでした。npx/uvx の場合、GUI アプリ環境の PATH にバイナリが含まれていないことがほとんどです — トラブルシューティング を参照。

[error] Server "postgres" exited with code 1: connection refused

接続文字列のホスト:ポートで Postgres が動いていません。DB を起動するか URI を直してください。

[error] Invalid env var GITHUB_PERSONAL_ACCESS_TOKEN: 401 Bad credentials

トークンが間違いか期限切れです — GitHub トークン で再発行してください。

自作サーバの計装

カスタムサーバ（カスタム stdio サーバ 参照）は構造化ログを stderr に書きます：

console.error(JSON.stringify({
  level: "info",
  msg: "tool called",
  tool: name,
  ts: new Date().toISOString(),
}));

stderr はクライアントのサーバ別ログにキャプチャされるため、MCP の stdio JSON-RPC フレームに影響を与えずに見えます。

ライブテール

macOS の Claude Desktop なら：

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

Claude を再起動する前に別端末で開いておけば、起動中にどのサーバがいつ接続（または失敗）したかが正確に分かります。

警告の扱い

@modelcontextprotocol/server-... パッケージの "deprecated" 警告は短期的には無視して構いませんが、env 変数名が変わっていないかパッケージの CHANGELOG をアップデート前に確認してください。