MCP（Model Context Protocol）サーバー連携のトラブルシューティング完全ガイド

MCP（Model Context Protocol）は、ClaudeなどのAIアシスタントを外部サービス（ファイルシステム、データベース、Slack、GitHub等）と接続するためのオープン標準プロトコルです。しかし「サーバーに接続できない」「ツールが認識されない」「設定ファイルの書き方がわからない」といった問題が多く報告されています。本記事では、よくあるエラーの原因と解決策を解説します。

問題の症状
原因の解説
- MCPの仕組み
- よくある原因
解決策
よく使われるMCPサーバー一覧
補足・注意点
- セキュリティの注意
- MCPサーバーが認識されない場合のチェックリスト
参照URL

問題の症状

問題1：MCPサーバーが認識されない

Claude Desktopの設定画面でMCPサーバーを設定したが、ツールが表示されない。

問題2：接続エラー

Error: Failed to connect to MCP server: spawn npx ENOENT

または：

Error: MCP server "filesystem" failed to start: Connection refused

問題3：ツール呼び出しエラー

Error executing tool: Permission denied

問題4：Claude Codeで `claude mcp` コマンドが失敗

$ claude mcp add filesystem
Error: Could not connect to server

原因の解説

MCPの仕組み

MCPはクライアント（Claude）とサーバー（外部ツール）の間の通信プロトコルです。

Claude（クライアント）
    ↕ MCP Protocol
MCPサーバー（filesystem, database, Slack等）
    ↕
外部システム

通信方式：

方式	説明	向いているケース
stdio	標準入出力	ローカルプロセス
SSE	Server-Sent Events	リモートサーバー
HTTP Streamable	HTTP + ストリーミング	リモートサーバー（新方式）

よくある原因

原因1：設定ファイルのパスが間違っている

Claude Desktopの設定ファイルは以下の場所にあります：

OS	設定ファイルパス
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Claude Codeの設定ファイルは：

スコープ	パス
User	`~/.claude/claude_mcp_config.json`
Project	`.claude/mcp.json`

原因2：Node.js / Python がインストールされていない（またはPATHに無い）

多くのMCPサーバーは npx （Node.js）または uvx / python で動作します。これらがインストールされていないか、PATH設定が不正だとサーバーが起動しません。

# 確認方法
node --version   # Node.js
npx --version    # npx
python --version # Python
uvx --version    # uv（Python パッケージマネージャー）

原因3：設定ファイルのJSON構文エラー

JSON内のカンマの有無、引用符のミス等でサーバーが起動しません。

原因4：MCPサーバーの権限エラー

ファイルシステムへのアクセスやネットワーク接続で権限エラーが発生することがあります。

解決策

ステップ1：Claude Desktop の設定ファイルを正しく書く

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-xxxxxxxxxxxx",
        "SLACK_TEAM_ID": "Txxxxxxxxx"
      }
    }
  }
}

重要：設定変更後は Claude Desktop を完全に再起動すること。

ステップ2：Claude Code でのMCP設定

# MCPサーバーをClaude Codeに追加
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# 追加済みのMCPサーバー一覧を確認
claude mcp list

# MCPサーバーの詳細を確認
claude mcp get filesystem

# MCPサーバーを削除
claude mcp remove filesystem

または .claude/mcp.json に直接設定：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "description": "プロジェクトのファイルシステムにアクセス"
    }
  }
}

ステップ3：接続問題のデバッグ

# MCPサーバーを手動で起動してエラーを確認
npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# Windowsの場合（npxのフルパスを使う）
"C:\Program Files\nodejs\npx.cmd" -y @modelcontextprotocol/server-filesystem C:\path\to\directory

ステップ4：Windowsでの追加設定

Windowsでは npx がPATHに存在しない場合、フルパスを指定する必要があります。

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Documents"
      ]
    }
  }
}

ステップ5：カスタムMCPサーバーの開発時のデバッグ

# MCP Inspectorを使ってサーバーをテスト
npx @modelcontextprotocol/inspector npx your-mcp-server

# または直接起動してstdio通信を確認
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | node your-mcp-server.js

よく使われるMCPサーバー一覧

サーバー名	パッケージ	機能
filesystem	`@modelcontextprotocol/server-filesystem`	ファイル読み書き
github	`@modelcontextprotocol/server-github`	GitHub操作
slack	`@modelcontextprotocol/server-slack`	Slack操作
postgres	`@modelcontextprotocol/server-postgres`	PostgreSQL操作
puppeteer	`@modelcontextprotocol/server-puppeteer`	Webブラウザ操作
memory	`@modelcontextprotocol/server-memory`	会話履歴管理
brave-search	`@modelcontextprotocol/server-brave-search`	Brave検索
google-maps	`@modelcontextprotocol/server-google-maps`	Google Maps