Claude Code MCPサーバー設定ガイド｜追加・削除・.mcp.jsonの書き方まで全手順

Claude Codeは単体でもファイル読み書きやBash実行が可能ですが、MCPサーバーを接続すると外部サービスとの連携が一気に広がります。GitHub上のIssue取得、PostgreSQLへの直接クエリ、Sentryのエラー監視――これらをClaude Codeの対話の中でシームレスに実行できるようになります。

MCP（Model Context Protocol）はAnthropicが策定したオープンソースの標準規格で、LLMと外部ツールを接続するためのプロトコルです。Claude Codeは2026年2月時点で、HTTP・SSE・stdioの3種類のトランスポートに対応し、数百のMCPサーバーと連携できます。

MCPサーバーの追加方法：3つのトランスポート

Claude CodeへのMCPサーバー追加は claude mcp add コマンドで行います。トランスポートの種類によって構文が異なります。

HTTP（リモート接続の推奨方式）

クラウドサービスが提供するMCPサーバーへの接続に適しています。SSEの後継として推奨されている方式です。

claude mcp add --transport http <サーバー名> <URL>

実行例：

# Notionに接続
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 認証ヘッダー付きで接続
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp \
  --header "Authorization: Bearer your-token"

SSE（Server-Sent Events）

SSEは非推奨（deprecated）となっています。HTTPトランスポートが利用可能な場合はそちらを使用してください。

claude mcp add --transport sse <サーバー名> <URL>

stdio（ローカルプロセス）

ローカルマシン上でプロセスとして実行するMCPサーバー向けです。npmパッケージやPythonスクリプトで提供されるサーバーの多くがこの方式を使います。

claude mcp add --transport stdio <サーバー名> -- <コマンド> [引数...]

実行例：

# Playwrightを追加（ブラウザ自動化）
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

# 環境変数を渡してAirtableサーバーを追加
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

注意すべきポイント： --transport、--env、--scope、--header などのオプションはサーバー名の前に記述します。--（ダブルダッシュ）はサーバー名とMCPサーバーに渡すコマンドを分離する役割を持ちます。

トランスポート方式の比較

項目	HTTP	SSE	stdio
接続先	リモートサーバー	リモートサーバー	ローカルプロセス
推奨度	推奨	非推奨（deprecated）	ローカル用途で推奨
認証	OAuth 2.0 / ヘッダー	ヘッダー	環境変数
代表的な用途	SaaS連携（GitHub, Sentry等）	レガシーサービス	npx/uvx経由のツール
ネットワーク要件	インターネット接続必須	インターネット接続必須	不要（ローカル実行）

設定ファイルの構造と保存場所

Claude CodeのMCP設定は複数のファイルに分散しています。どのファイルが何を管理しているかを把握しておくと、設定のトラブル時に原因を切り分けやすくなります。

設定ファイル一覧

ファイル	保存場所	役割	共有対象
`~/.claude.json`	ホームディレクトリ	ユーザー/ローカルスコープのMCPサーバー設定	個人（共有不可）
`.mcp.json`	プロジェクトルート	プロジェクトスコープのMCPサーバー設定	チーム（Gitで共有）
`~/.claude/settings.json`	ホームディレクトリ	MCP有効/無効の制御、権限設定	個人
`.claude/settings.json`	プロジェクトルート	プロジェクト共有の権限・設定	チーム
`.claude/settings.local.json`	プロジェクトルート	個人のローカル上書き設定	個人（gitignore対象）
`managed-mcp.json`	システムディレクトリ	企業管理者によるMCPサーバー一元管理	組織全体

.mcp.jsonの書式

プロジェクトスコープで共有するMCPサーバー設定は .mcp.json に記述します。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_CONNECTION_STRING}"],
      "env": {
        "DB_CONNECTION_STRING": "${DB_CONNECTION_STRING}"
      }
    }
  }
}

.mcp.json 内では環境変数の展開がサポートされています。

サポートされている構文：

${VAR} — 環境変数VARの値に展開
${VAR:-default} — VARが未設定の場合はdefaultを使用

展開できるフィールド： command、args、env、url、headers

チームで利用する際は、APIキーなどの秘匿情報を ${VAR} 形式で記述し、各メンバーが自身の環境変数で値を設定する運用が安全です。

スコープの選び方：ローカル・プロジェクト・ユーザー

MCPサーバーの設定には3つのスコープがあり、--scope フラグで指定します。

ローカルスコープ（デフォルト）

--scope local またはフラグ省略時に適用されます。設定は ~/.claude.json 内のプロジェクトパス配下に保存され、自分専用・現プロジェクト限定で有効です。

# ローカルスコープ（デフォルト）
claude mcp add --transport http stripe https://mcp.stripe.com

適する場面： 個人の実験的なサーバー、機密認証情報を含むサーバー、特定プロジェクトでのみ使うサーバー

プロジェクトスコープ

--scope project を指定すると、プロジェクトルートの .mcp.json に設定が書き込まれます。Gitリポジトリにコミットしてチームで共有する想定です。

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

適する場面： チーム全員が使う外部サービス連携、プロジェクト固有のツール

セキュリティ上の注意： .mcp.json からプロジェクトスコープのサーバーを利用する際、Claude Codeは初回に承認を求めます。承認選択をリセットするには claude mcp reset-project-choices を実行してください。

ユーザースコープ

--scope user を指定すると、~/.claude.json のグローバル領域に保存されます。マシン上の全プロジェクトで利用可能です。

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

適する場面： 複数プロジェクトで横断的に使うツール（GitHub、個人用ユーティリティなど）

スコープの優先順位

同名のサーバーが複数スコープに存在する場合、次の優先順序で解決されます。

ローカル > プロジェクト > ユーザー

個人設定で共有設定を上書きできる仕組みです。

MCPサーバーの管理コマンド

日常的に使う管理コマンドの一覧です。

# 設定済みサーバーの一覧表示
claude mcp list

# 特定サーバーの詳細情報を表示
claude mcp get <サーバー名>

# サーバーを削除
claude mcp remove <サーバー名>

# JSON形式で直接追加
claude mcp add-json <サーバー名> '<JSON>'

# Claude Desktopから設定をインポート
claude mcp add-from-claude-desktop

# Claude Code内でサーバーステータスを確認
/mcp

JSON形式での直接追加

既存のJSON設定をそのまま投入したい場合に便利です。

# HTTPサーバーをJSON形式で追加
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdioサーバーをJSON形式で追加
claude mcp add-json local-tool '{"type":"stdio","command":"/path/to/server","args":["--config","config.json"],"env":{"CACHE_DIR":"/tmp"}}'

Claude Desktopからのインポート

Claude Desktopで既にMCPサーバーを設定済みの場合、ワンコマンドでインポートできます。

claude mcp add-from-claude-desktop

macOSとWSL環境で利用可能です。インポート後は claude mcp list で確認してください。

実践的なMCPサーバー設定例

GitHub連携

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

追加後、Claude Code内で /mcp コマンドを実行し、GitHubアカウントで認証します。PRのレビュー依頼やIssue作成をClaude Codeの対話内で完結できるようになります。

PostgreSQLデータベースクエリ

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@db.example.com:5432/mydb"

自然言語でデータベースにクエリを投げられます。読み取り専用のユーザーで接続することを推奨します。

Sentry エラー監視

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

直近24時間のエラー傾向の確認、スタックトレースの表示、どのデプロイでエラーが増加したかの特定などが可能です。

Context7（ライブラリドキュメント参照）

claude mcp add --transport stdio context7 -- npx -y @upstash/context7-mcp@latest

ライブラリの最新ドキュメントをClaude Codeのコンテキストに直接取り込めます。

MCPリソースとプロンプトの活用

MCPサーバーはツール（関数呼び出し）だけでなく、リソースとプロンプトも提供できます。

リソースの参照

MCPサーバーが公開するリソースは @ メンションで参照できます。ファイル参照と同様の操作感です。

# GitHubのIssueを参照
> @github:issue://123 の内容を分析して修正案を提示してください

# 複数リソースの同時参照
> @postgres:schema://users と @docs:file://database/user-model を比較してください

プロンプト入力時に @ を入力すると、接続されたMCPサーバーのリソースがオートコンプリートに表示されます。

MCPプロンプトをスラッシュコマンドとして使用

MCPサーバーが定義するプロンプトは、/mcp__サーバー名__プロンプト名 の形式でスラッシュコマンドとして実行できます。

# GitHubのPR一覧を取得
> /mcp__github__list_prs

# 引数付きでPRレビューを実行
> /mcp__github__pr_review 456

/ を入力すると利用可能なMCPプロンプトが一覧表示されます。

Claude CodeをMCPサーバーとして公開する

Claude Code自体をMCPサーバーとして起動し、Claude Desktopなど他のMCPクライアントから利用する方法があります。

claude mcp serve

Claude Desktopの claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

command フィールドには claude コマンドのフルパスを指定する必要がある場合があります。which claude で確認してください。

–mcp-configによる設定ファイルの切り替え

用途ごとにMCP設定ファイルを分けたい場合、--mcp-config オプションでJSONファイルを指定してClaude Codeを起動できます。

# 開発用の設定で起動
claude --mcp-config ~/mcp-configs/dev.json

# データ分析用の設定で起動
claude --mcp-config ~/mcp-configs/analytics.json

シェルのエイリアスと組み合わせると、切り替えがさらに簡単になります。

# ~/.bashrc や ~/.zshrc に追加
alias c-dev='claude --mcp-config ~/mcp-configs/dev.json'
alias c-data='claude --mcp-config ~/mcp-configs/analytics.json'

Windows環境での注意点

ネイティブWindows（WSLではない）で npx を使うstdioサーバーを追加する場合、cmd /c ラッパーが必要です。

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

cmd /c がないと「Connection closed」エラーが発生します。WSL2環境であればLinuxと同じコマンドで動作します。

企業向け：managed-mcp.jsonによる一元管理

組織全体でMCPサーバーを統制する場合、システムディレクトリに managed-mcp.json を配置します。

配置先：

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux / WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

このファイルが存在すると、ユーザーは独自のMCPサーバーを追加できなくなり、管理者が定義したサーバーのみ利用可能になります。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

より柔軟な制御が必要な場合は、managed-settings.json の allowedMcpServers / deniedMcpServers でポリシーベースの許可・拒否リストを設定できます。

出力制限とタイムアウトの調整

MCPサーバーの応答が大きい場合やサーバー起動が遅い場合の調整方法です。

環境変数	デフォルト値	説明
`MAX_MCP_OUTPUT_TOKENS`	25,000	MCPツール応答の最大トークン数（10,000超で警告表示）
`MCP_TIMEOUT`	—	MCPサーバー起動のタイムアウト（ミリ秒）
`MCP_TOOL_TIMEOUT`	—	MCPツール実行のタイムアウト（ミリ秒）

# 例：出力上限を50,000トークンに拡大して起動
MAX_MCP_OUTPUT_TOKENS=50000 claude

# 例：起動タイムアウトを10秒に設定
MCP_TIMEOUT=10000 claude

トラブルシューティング

MCPサーバーが認識されない

サーバーの状態を確認: Claude Code内で /mcp を実行し、サーバーのステータスを確認します
設定の一覧確認: claude mcp list で登録済みサーバーを表示します
スコープの確認: 意図したスコープに登録されているか claude mcp get <サーバー名> で確認します
再起動: MCPサーバーの設定変更後はClaude Codeの再起動が必要な場合があります

「Connection closed」エラー（Windows）

ネイティブWindowsで npx を使用する場合、cmd /c ラッパーを付けて再登録してください。

claude mcp remove my-server
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

プロジェクトスコープのサーバーが使えない

.mcp.json で定義されたプロジェクトスコープのサーバーは、初回利用時に承認が必要です。承認状態をリセットするには以下を実行します。

claude mcp reset-project-choices

また、settings.json で以下を設定すると、プロジェクトの全MCPサーバーを自動承認できます。

{
  "enableAllProjectMcpServers": true
}

特定のサーバーのみ承認・拒否する場合は enabledMcpjsonServers / disabledMcpjsonServers を使います。

{
  "enabledMcpjsonServers": ["github", "playwright"],
  "disabledMcpjsonServers": ["filesystem"]
}

OAuth認証の問題

HTTPトランスポートのサーバーでOAuth認証が必要な場合、/mcp コマンドで認証フローを開始できます。ブラウザが自動で開かない場合は、表示されたURLを手動でコピーしてください。認証トークンは安全に保存され、自動的に更新されます。認証を取り消すには /mcp メニューの「Clear authentication」を選択します。

まとめ

Claude CodeのMCPサーバー設定で押さえておくべきポイントを整理します。

トランスポートは3種類: リモート接続にはHTTP（推奨）、ローカルツールにはstdioを選択
スコープの使い分け: 個人用はローカル、チーム共有はプロジェクト（.mcp.json）、全プロジェクト共通はユーザー
設定ファイルの環境変数展開: ${VAR} 構文でAPIキーを安全に管理
管理コマンド: claude mcp list / get / remove で日常管理
企業管理: managed-mcp.json で組織全体のサーバーを統制可能
トラブル時: /mcp コマンドでステータス確認、Windows環境は cmd /c ラッパーを忘れずに

MCPの設定は公式ドキュメント（code.claude.com/docs/ja/mcp）で最新情報が確認できます。新しいMCPサーバーは GitHub で数百種類以上が公開されており、開発ワークフローに合わせて自由に組み合わせられます。

MCPサーバーの追加方法：3つのトランスポート#

HTTP（リモート接続の推奨方式）#

SSE（Server-Sent Events）#

stdio（ローカルプロセス）#

トランスポート方式の比較#

設定ファイルの構造と保存場所#

設定ファイル一覧#

.mcp.jsonの書式#

スコープの選び方：ローカル・プロジェクト・ユーザー#

ローカルスコープ（デフォルト）#

プロジェクトスコープ#

ユーザースコープ#

スコープの優先順位#

MCPサーバーの管理コマンド#

JSON形式での直接追加#

Claude Desktopからのインポート#

実践的なMCPサーバー設定例#

GitHub連携#

PostgreSQLデータベースクエリ#

Sentry エラー監視#

Context7（ライブラリドキュメント参照）#

MCPリソースとプロンプトの活用#

リソースの参照#

MCPプロンプトをスラッシュコマンドとして使用#

Claude CodeをMCPサーバーとして公開する#

–mcp-configによる設定ファイルの切り替え#

Windows環境での注意点#

企業向け：managed-mcp.jsonによる一元管理#

出力制限とタイムアウトの調整#

トラブルシューティング#

MCPサーバーが認識されない#

「Connection closed」エラー（Windows）#

プロジェクトスコープのサーバーが使えない#

OAuth認証の問題#

まとめ#