はじめに
Model Context Protocol（MCP）を利用してクライアント（Claude DesktopやCursorなど）とMCPサーバーを連携させる際、「サーバーが認識されない」「ツールが呼び出せない」といった接続トラブルが発生することがあります。
本記事では、MCPサーバーが正常に動作しない場合に確認すべき項目を整理し、設定例やデバッグ方法を交えたトラブルシューティング用のチェックリストを提供します。
この記事で分かること
- MCPサーバー接続トラブルの主な原因と対策
- 設定ファイル（
claude_desktop_config.json等）の記述形式と注意点 - MCP Inspectorを使用したデバッグ手順
- 実務で使えるトラブルシューティング・チェックリスト
前提条件
- Node.js（npx）または Python（uv / pip）環境がインストールされていること
- MCPクライアント（Claude Desktopなど）が導入されていること
トラブルシューティング手順とチェックポイント
MCPサーバーの接続失敗は、大きく分けて**「設定・パスの問題」「環境・依存関係の問題」「通信・プロトコルの問題」**の3つに分類できます。
1. 設定ファイルの構文とパスの確認
最も頻度の高い原因は、設定ファイルの記述ミスや環境変数の不備です。
設定例（Claude Desktopの場合）
以下は、Node.jsベースおよびPythonベースのMCPサーバーを登録する際の基本設定例です。
{
"mcpServers": {
"example-node-server": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop"
]
},
"example-python-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/server",
"run",
"server.py"
],
"env": {
"API_KEY": "your_api_key_here"
}
}
}
}
確認ポイント
- JSON構文チェック: カンマの付け忘れやダブルクォーテーションの欠落がないか確認します。
-
絶対パスの利用: 相対パス（
./など）はクライアントの実行ディレクトリに依存するため、実行ファイルのパスや対象ディレクトリは原則として絶対パスで記述します。 -
コマンドの実行権限:
npxやuvなどのコマンドが、クライアントプロセスから参照できる環境変数（PATH）上に存在しているか確認します。
2. 標準入出力（stdio）とログ出力の干渉
stdio（標準入出力）トランスポートを利用するMCPサーバーでは、標準出力（stdout）がJSON-RPCメッセージの伝送に使用されます。
よくある失敗パターン
サーバー実装側で console.log() や print() を使用してデバッグログを標準出力に流すと、JSON-RPCメッセージが破損し、クライアント側で解析エラー（Parse Error）が発生します。
対処方法
-
ログは標準エラー出力（stderr）に出力する
- Node.js:
console.error()を使用 - Python:
sys.stderr.write()またはloggingモジュールで出力先をsys.stderrに設定
- Node.js:
3. MCP Inspectorによるデバッグ
クライアント経由で動作しない場合は、公式から提供されているデバッグツール @modelcontextprotocol/inspector を使用して、サーバー単体で正常に動作するか切り分けを行います。
実行コマンド例
npx @modelcontextprotocol/inspector node /path/to/your/index.js
Python（uv）の場合:
npx @modelcontextprotocol/inspector uv --directory /path/to/your/server run server.py
実行後に表示されるローカルURLにブラウザでアクセスすることで、以下の確認が行えます。
- Tools / Resources の一覧取得: 定義したツールが正しくレスポンスを返すか
- Toolの実行テスト: 入力パラメータを渡して適切なレスポンスが返るか
- エラーログの確認: サーバー内部で発生している例外の確認
Inspectorで動作し、クライアント側で動作しない場合は、クライアントの設定ファイル（パス指定や環境変数）に原因があると特定できます。
実務用トラブルシューティング・チェックリスト
障害発生時は以下の項目を順番に確認してください。
| 分類 | 確認項目 | 状態 | 対策・確認内容 |
|---|---|---|---|
| 設定 | JSONの構文エラーはないか | [ ] | カンマ不足、閉じ括弧忘れ、ダブルクォーテーションの漏れを確認 |
| 設定 | パス指定は絶対パスになっているか | [ ] | 実行スクリプトや参照ディレクトリを絶対パスに修正 |
| 設定 | 必要な環境変数が設定されているか | [ ] |
env フィールドにAPIキーや設定値が定義されているか確認 |
| 環境 | コマンド（node, python, uv 等）にパスが通っているか |
[ ] | 端末で直接実行可能か確認。必要に応じてフルパス指定を検討 |
| 実装 | 標準出力（stdout）に不要なログを出していないか |
[ ] | デバッグ出力が stderr に向いているかコードを確認 |
| 実装 | JSON-RPCのレスポンス形式が正しいか | [ ] | MCP InspectorでToolのレスポンス形式を確認 |
| 運用 | 変更後にクライアントを再起動したか | [ ] | 設定ファイルの更新後、アプリを完全再起動して反映を確認 |
注意点・ハマりやすいポイント
-
環境変数の引き継ぎ
OSのシェル上で設定した環境変数（.bashrcや.zshrcなど）は、GUIアプリ（Claude Desktopなど）から起動されたMCPサーバーに引き継がれない場合があります。必要な環境変数は、設定ファイルのenvブロック内に明示的に記述してください。 -
Node.js / Pythonのバージョン依存
使用するSDKやパッケージが要求するランタイムのバージョンを満たしているか確認してください。複数のバージョンを管理している場合は、実行するバイナリの絶対パス（例:/usr/local/bin/node）をcommandに直接指定する構成も有効です。 -
仕様変更の確認
MCPの仕様および関連ライブラリは更新が行われる可能性があるため、実装時や不具合発生時には最新の公式ドキュメントを参照してください。
まとめ
MCPサーバーの接続問題が発生した際は、まず「JSON設定とパスの正確性」を確認し、次に「MCP Inspectorを用いた単体テスト」で切り分けることが解決の近道です。ログ出力先の管理と環境変数の明示的な設定を意識してデバッグを進めてください。