Claude Code MCPサーバー連携ガイド｜導入から実践まで
Claude CodeでMCPサーバーを導入・設定する手順をOS別に解説。おすすめサーバーの紹介、環境変数やスコープの使い分け、頻出エラーの対処法まで網羅します。
Claude Code MCPサーバー連携ガイドとして、 導入から実践までを体系的にまとめました。 MCPを使えば、GitHub・データベース・ブラウザ自動化といった 外部ツールをClaude Codeから直接操作できます。 たとえばGitHub MCPサーバーを接続するだけで、 Issue作成やPRレビューをターミナルから完結させられます。 この記事を読み終えるころには、MCPサーバーの選定・ インストール・設定・トラブル対応まで 一通りこなせるようになっているはずです。
MCPとは？Claude Codeを拡張する標準プロトコル
MCP（Model Context Protocol）は、 AIと外部ツールをつなぐ共通規格です。 Anthropicが開発したオープンソースの標準プロトコルで、 GitHub・データベース・ブラウザ自動化など、 さまざまな外部システムとClaude Codeを接続できます （Anthropic公式ブログ）。
USBがあらゆる周辺機器を統一規格で接続したように、 MCPはAIと外部ツール間の通信を標準化しています。 個別のAPI連携コードを書く必要はありません。
MCPの基本概念とコアコンポーネント
MCPは3つのコアコンポーネントで構成されています。
| コンポーネント | 役割 | 具体例 |
|---|---|---|
| MCPサーバー | 外部ツールの機能を提供する側 | GitHub MCP、Sentry MCP |
| MCPクライアント | サーバーに接続してツールを呼び出す側 | Claude Code本体 |
| トランスポート | サーバーとクライアント間の通信方式 | stdio、HTTP、SSE |
通信にはJSON-RPC 2.0プロトコルを使用します （MCPcat）。 Claude Codeがクライアントとして動作し、 各MCPサーバーから「ツール」「リソース」「プロンプト」の 3種類の機能を受け取る仕組みです。
たとえばGitHub MCPサーバーを接続すると、 Issue作成やPRレビューといった操作を Claude Codeから直接実行できるようになります。
3つのトランスポート（stdio・HTTP・SSE）の選び方
Claude Codeは3つのトランスポートに対応しています （公式ドキュメント）。 用途に応じた使い分けが必要です。
stdio（標準入出力） は、
ローカルで動作するMCPサーバー向けの方式です。
npxやuvxでプロセスを起動し、
標準入出力でJSON-RPCメッセージをやり取りします。
ローカル開発では最も手軽な選択肢です。
HTTP（Streamable HTTP） は、 リモートサーバー向けの推奨方式です。 URLを指定するだけで接続でき、 OAuth 2.0認証にも対応しています。 チームで共有するサーバーにはこの方式を選んでください。
SSE（Server-Sent Events） は、 HTTPの前身にあたるレガシー方式です。 2026年現在、公式では非推奨とされています。 既存のSSEサーバーとの互換性のために残されていますが、 新規導入ではHTTPを選ぶのが賢明です。
迷ったときの判断基準はシンプルです。 ローカルのCLIツールを動かすならstdio、 リモートのAPIサービスに接続するならHTTPを選んでください。
前提条件とOS別の環境構築
MCPサーバーを動かすには、いくつかのソフトウェアが必要です。 環境の不一致はトラブルの最大要因なので、先に確認しておきましょう。
必須ソフトウェアとバージョン確認
以下の2つが揃っているか確認してください。
- Node.js 18以上（LTS版を推奨）
- Claude Code 最新版
Node.js 18未満では互換性エラーが発生します（Claude MCPの導入方法ガイド）。まずバージョンを確認しましょう。
# macOS / Linux
node --version
claude --version# Windows PowerShell
node --version
claude --versionnode --version の出力が v18.0.0 以上であればOKです。
古い場合は Node.js公式サイト からLTS版をインストールしてください。
macOS・Windows・Linuxごとの初期セットアップ
OS間でコマンドはほぼ共通ですが、設定パスとWindows固有の注意点に違いがあります。
macOSの場合
設定ファイルのパスは以下のとおりです。
~/Library/Application Support/Claude/claude_desktop_config.jsonHomebrewでnvmを入れている場合、PATHが通らないことがあります。
which node でフルパスを確認し、設定ファイルにはフルパスを指定してください。
「spawn ENOENT」エラーの主因はこのPATH問題です
（GitHub Discussion #20）。
Windowsの場合
設定ファイルのパスはこちらです。
%APPDATA%\Claude\claude_desktop_config.jsonWindowsでは npx を使うローカルMCPサーバーに
cmd /c ラッパーが必須です
（Claude Code公式ドキュメント）。
これを省略すると「Connection closed」エラーが起きます。
{
"mcpServers": {
"example": {
"command": "cmd",
"args": ["/c", "npx", "-y", "example-mcp-server"]
}
}
}また、JSONファイル内のパス指定にはダブルバックスラッシュ（\\）を使ってください。
シングルバックスラッシュはパースエラーの原因になります。
Linux（WSL含む）の場合
Claude Desktopアプリはlinuxネイティブには対応していません。
Claude Code CLIを直接使う形になります。
WSL環境の場合、managed-mcp.jsonの配置先は /etc/claude-code/ です。
Node.jsのインストールには nvm の利用が安定しています。
# nvmでNode.js LTSをインストール
nvm install --lts
nvm use --ltsMCPサーバーのインストールと設定ファイル
Claude CodeへのMCPサーバー追加はclaude mcp addコマンドで行います。
トランスポートの種類、スコープの選択、環境変数の扱いを押さえれば、
迷わず設定できます。
3つのインストール方法（HTTP・SSE・stdio）
Claude Codeは3種類のトランスポート（通信方式）に対応しています（Claude Code公式ドキュメント）。
1. リモートHTTPサーバー（推奨）
クラウド上のMCPサーバーに接続する方法です。
# macOS / Linux
claude mcp add --transport http my-server https://example.com/mcp# Windows PowerShell
claude mcp add --transport http my-server https://example.com/mcp2. リモートSSEサーバー（非推奨）
SSE（Server-Sent Events）方式は現在レガシー扱いです。新規導入ではHTTPを選んでください。
3. ローカルstdioサーバー
ローカルでプロセスを起動し、標準入出力で通信します。Windowsではcmd /cラッパーが必須です（公式ドキュメント）。
# macOS / Linux
claude mcp add my-server npx -y @example/mcp-server# Windows PowerShell（cmd /cラッパーが必要）
claude mcp add my-server cmd /c npx -y @example/mcp-serverスコープ（local・project・user）と.mcp.jsonの書き方
--scopeオプションで、サーバーの有効範囲を指定します。
| スコープ | 保存先 | 用途 |
|---|---|---|
| local（既定） | .claude/ | 個人の開発環境用 |
| project | .mcp.json | チーム共有（Git管理向き） |
| user | ~/.claude.json | 全プロジェクト共通 |
チームで共有するにはprojectスコープが便利です。
claude mcp add --scope project github-server npx -y @modelcontextprotocol/server-github生成される.mcp.jsonの構造は以下のとおりです。
{
"mcpServers": {
"github-server": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}環境変数展開とセキュアな認証設定
.mcp.jsonでは${VAR}構文で環境変数を展開できます
（公式ドキュメント）。
APIキーをファイルに直書きせず、安全に管理できる仕組みです。
{
"env": {
"API_KEY": "${MY_API_KEY}",
"REGION": "${AWS_REGION:-us-east-1}"
}
}${VAR:-default}構文を使えば、未設定時のデフォルト値も指定できます。
⚠️ 注意: .mcp.jsonをGitにコミットする場合、APIキーなどの秘密情報は必ず環境変数経由で渡してください。値を直接記述すると漏洩リスクがあります。
リモートサーバーでOAuth 2.0認証が必要な場合は、
/mcpコマンドからブラウザ経由の認証フローを実行できます。
トークンはClaude Codeが自動管理するため、手動更新は不要です。
実践セットアップ：おすすめMCPサーバーと活用例
MCPサーバーは用途に合わせて選ぶのがコツです。 ここでは実務で役立つサーバーの紹介と、具体的な設定手順を解説します。
用途別おすすめMCPサーバー（GitHub・Playwright・SQLiteほか）
2026年時点で、Claude Codeとの相性が良いMCPサーバーを用途別に整理しました（AI Career Japan）。
| 用途 | サーバー名 | 主な機能 |
|---|---|---|
| コードレビュー | GitHub MCP | PR作成・Issue管理・差分確認 |
| ブラウザテスト | Playwright MCP | E2Eテスト自動化・スクリーンショット取得 |
| データベース操作 | SQLite MCP | ローカルDBへのクエリ実行・スキーマ確認 |
| エラー監視 | Sentry MCP | 例外追跡・エラー分析・アラート連携 |
| 推論強化 | Sequential Thinking | 複雑な問題の段階的な思考整理 |
| プロジェクト管理 | Notion MCP | ページ作成・タスク管理・ドキュメント検索 |
信頼できる公式・準公式のサーバーを優先してください。 サードパーティ製はソースコードを確認してから導入するのが安全です。
ステップバイステップ設定例：GitHubサーバーとSentry
GitHubサーバーの追加手順を例に、実際の流れを示します。
- MCPサーバーを追加します。 Claude Code上で以下を実行してください。
# macOS / Linux
claude mcp add github -s user -- npx -y @modelcontextprotocol/server-github# Windows PowerShell（cmd /c ラッパーが必須）
claude mcp add github -s user -- cmd /c npx -y @modelcontextprotocol/server-github-s user を指定すると、全プロジェクトで使えます（Claude Code公式ドキュメント）。
- 環境変数でトークンを設定します。
APIキーは
.mcp.jsonに直書きせず、環境変数で渡してください。
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}⚠️ .mcp.jsonをGitにコミットする場合、${VAR}構文を使えばトークンの漏洩を防げます（Claude Code公式ドキュメント）。
- 動作を確認します。 Claude Codeを再起動し、「GitHubのIssue一覧を取得して」と指示してみてください。 ツール一覧にGitHub関連の操作が表示されれば成功です。
Sentryも同様の手順で追加できます。
@sentry/mcp-serverを指定し、
SENTRY_AUTH_TOKENを環境変数に設定してください。
高度な機能：リソース参照・スラッシュコマンド・動的更新
MCPにはツール呼び出し以外にも便利な機能があります。
リソースの@メンション参照では、 MCPサーバーが提供するデータをコンテキストに含められます。 形式は以下のとおりです。
@server:protocol://resource/pathたとえば@github:repo://owner/repoのように入力すると、リポジトリ情報が自動取得されます（Claude Code公式ドキュメント）。
MCPプロンプトのスラッシュコマンド化も実用的な機能です。 サーバーが定義したプロンプトは、以下の形式で呼び出せます。
/mcp__servername__promptname 引数1 引数2スペース区切りで引数を渡す仕組みです。
動的ツール更新により、
サーバー側でツール定義が変わっても再接続は不要です。
list_changed通知（MCPプロトコルの機能）を通じて、
利用可能なツール・プロンプト・リソースがリアルタイムに反映されます。
トラブルシューティング：頻出エラーと解決法
MCPサーバー連携で発生しやすいエラーには共通パターンがあります。 ここでは、Claude Code公式ドキュメントや GitHub Issuesで報告の多い問題を整理しました。
spawn ENOENTとConnection closedの原因と対処
spawn ENOENTは最も遭遇しやすいエラーです。
原因はPATHの問題で、指定した実行ファイルをシステムが見つけられない状態を指します
（GitHub Discussion #20）。
以下のコマンドでパスを確認してください。
# macOS / Linux：npxのフルパスを確認
which npx# Windows PowerShell：npxのフルパスを確認
Get-Command npx | Select-Object Source設定ファイルには、取得したフルパスを指定します。
{
"command": "/usr/local/bin/npx"
}WindowsでConnection closedが頻発する場合、
cmd /cラッパーの欠落が原因です。
Windows環境では以下のように記述してください。
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-example"]
}stdout混在・JSON-RPCエラー・Node.jsバージョン問題
stdoutの混在問題は見落としやすいトラブルです。
MCPサーバーはstdoutにJSON-RPCメッセージのみを出力する必要があります。
console.log()を使うとプロトコルが破損するため、
デバッグ出力はすべてconsole.error()（stderr）に送ってください
（Stainless MCP Portal）。
JSON-RPCエラーコードの代表例は次のとおりです。
| コード | 意味 | 主な原因 |
|---|---|---|
| -32700 | Parse Error | JSONの構文ミス |
| -32600 | Invalid Request | 必須フィールドの欠落 |
| -32601 | Method Not Found | サーバー未対応のメソッド呼び出し |
Node.jsバージョンは18以上が必須です。18未満では互換性エラーが発生します。
# macOS / Linux
node -v # v18以上であることを確認# Windows PowerShell
node -v # v18以上であることを確認LTS版の使用を推奨します。
nvmを使っている場合はnvm use --ltsで切り替えられます。
MCP Inspectorによるデバッグと企業向け管理機能
問題の切り分けには MCP Inspector が有効です。 ホストアプリケーションなしでサーバー単体をテストできるため、 Claude Code側の問題かサーバー側の問題かを素早く判別できます。
出力が大きすぎる場合、10,000トークンを超えると警告が表示されます。 上限の調整は環境変数で対応してください。
# macOS / Linux
export MAX_MCP_OUTPUT_TOKENS=20000# Windows PowerShell
$env:MAX_MCP_OUTPUT_TOKENS = "20000"企業環境ではmanaged-mcp.jsonによる集中管理が可能です。
配置場所はOSごとに異なります。
| OS | パス |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/ |
| Linux / WSL | /etc/claude-code/ |
| Windows | C:\Program Files\ClaudeCode\ |
このファイルはシステム全体のパスに置かれるため、管理者権限が必要です。 一般ユーザーは編集できない点に注意してください。 組織のセキュリティポリシーに応じて、 許可リストや拒否リストによるサーバー制御を設定できます （Claude Code公式ドキュメント）。
まとめ：MCPサーバーを1つ導入して開発フローを変えよう
MCPサーバー連携の第一歩として、 まずは自分の開発で最も頻度の高い作業を1つ自動化してみてください。 GitHub MCPでPR操作を効率化するもよし、 Playwright MCPでE2Eテストを対話的に実行するもよし。 1つのサーバーを使いこなしてから次を追加する方が、 設定ミスやエラー対応に追われずに済みます。
慣れてきたら、.mcp.jsonをリポジトリに含めて
チーム全体で設定を共有する運用に進みましょう。
環境変数展開（${VAR}構文）を活用すれば、
APIキーをgitにコミットするリスクも避けられます。
企業での導入を検討しているなら、
managed-mcp.jsonによる集中管理も視野に入れてください。
さらに一歩進みたい方は、 MCP SDKを使ったカスタムサーバーの自作に挑戦してみてください。 TypeScriptまたはPythonで、 社内APIや独自ツールをMCP経由でClaude Codeに接続できます。 公式ドキュメント（Claude Code MCP）と MCP仕様（modelcontextprotocol.io）が最新の情報源です。 MCPの仕様は進化が速く、SSEの非推奨化のように変更が入ることもあります。 定期的に公式を確認する習慣をつけておきましょう。
参考文献
- https://www.anthropic.com/news/model-context-protocol
- https://code.claude.com/docs/ja/mcp
- https://ainow.jp/claude-mcp-guide/
- https://github.com/orgs/modelcontextprotocol/discussions/20
- https://www.stainless.com/mcp/error-handling-and-debugging-mcp-servers
- https://ai-career-japan.jp/posts/claude-code-mcp-%E3%81%8A%E3%81%99%E3%81%99%E3%82%81%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E5%AE%8C%E5%85%A8%E3%82%AC%E3%82%A4%E3%83%89/
- https://modelcontextprotocol.io/docs/develop/connect-local-servers
- https://mcpcat.io/guides/error-handling-custom-mcp-servers/