MCP Plugins 統合 — ローカル・リモート MCP サーバーの設定

読了 10分＋実践 30分

`settings.json` の基本構造（権限・フック）を理解しており、Claude Code の機能を外部ツールと連携させたい方。[Settings JSON 設計](./settings) を先に読むことを推奨します。

`.claude/settings.json` の基本構造を把握していること
npm / npx の基本操作ができること
連携したい外部サービス（GitHub など）の API トークンを取得していること

MCP サーバーを設定すると、Claude Code は Web 検索・GitHub API・ローカルファイルシステムなどの外部ツールを直接操作できるようになります。このページでは、MCP の概念から settings.json への設定方法、認証情報の安全な管理まで順番に学びます。

MCP とは何か

MCP（Model Context Protocol: モデルコンテキストプロトコル）とは、Claude が外部ツール・データソースと通信するための標準プロトコルです。MCP サーバーは Claude からの要求を受け取り、外部サービスへの橋渡しを行うプロセスとして動作します。

MCP を使わない場合、Claude はセッション中に渡されたテキストだけを頼りに回答します。MCP を設定することで、Claude は「ファイルを読み書きする」「GitHub のプルリクエスト一覧を取得する」「データベースを検索する」といった実際のアクションを実行できるようになります。

ローカル MCP とリモート MCP の違い

MCP サーバーには、ユーザーのマシン上で動作するローカル MCP と、クラウドサーバーに接続するリモート MCP の 2 種類があります。

項目	ローカル MCP	リモート MCP
実行場所	ユーザーのマシン上	クラウドサーバー
起動方法	`command` でプロセスを起動する	`url` で接続する
認証	不要（またはローカル設定のみ）	API キー・OAuth
用途	ファイルシステム・ローカル DB	GitHub・Slack・外部 API
例	`@modelcontextprotocol/server-filesystem`	GitHub MCP サーバー

ローカル MCP はインターネット接続なしで動作するため、社内ファイルや機密データを扱う場面に適しています。リモート MCP は外部サービスの API を Claude から直接呼び出したい場合に使います。

仕組み: settings.json での設定方法

MCP サーバーは .claude/settings.json の mcpServers セクションで定義します。

基本構造

{
  "mcpServers": {
    "サーバー名": {
      "command": "実行コマンド",
      "args": ["引数1", "引数2"],
      "env": {
        "ENV_VAR": "${ENV_VAR}"
      }
    }
  }
}

設定フィールドの説明

フィールド	種別	説明
`command`	ローカル用	実行するコマンド（`npx`、`node`、`python` など）
`args`	ローカル用	`command` に渡す引数の配列
`env`	ローカル用	MCP サーバープロセスに渡す環境変数
`url`	リモート用	リモートサーバーの URL（`https://...` または `ws://...`）

設定例: GitHub MCP とファイルシステム MCP

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    }
  }
}

${GITHUB_TOKEN} と書くと、Claude Code はシェルの環境変数 GITHUB_TOKEN を参照します。API キーをファイルに直接書き込まずに済むため、この形式を使います。

ベストプラクティス

認証情報は環境変数参照で渡す

API キーを settings.json に直接記述すると、そのファイルをコミットした際に認証情報が漏洩します。${VAR_NAME} の形式で環境変数を参照し、実際の値はシェルプロファイル（.zshrc や .bashrc）または settings.local.json の env セクションに置きます。

// 避けるべき設定: API キーを直接書く
"env": {
  "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}

// 推奨: 環境変数を参照する
"env": {
  "GITHUB_TOKEN": "${GITHUB_TOKEN}"
}

秘密情報は settings.local.json に置く

チームで共有する settings.json には認証情報を含めません。個人の API キーや実験的な MCP サーバーは settings.local.json に定義します。settings.local.json は .gitignore で除外されているため、リポジトリに含まれません。

ファイルシステム MCP はアクセス範囲を絞る

@modelcontextprotocol/server-filesystem はパスを指定してアクセス範囲を制限します。プロジェクトに関係のないホームディレクトリ全体を開放するのではなく、作業対象のディレクトリだけを指定します。

// 避けるべき設定: ホームディレクトリ全体を開放
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]

// 推奨: 特定のプロジェクトディレクトリに限定
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]

MCP サーバーは信頼できるソースから導入する

MCP サーバーは Claude の代わりに外部システムへのアクセスを行うプロセスです。公式の @modelcontextprotocol/server-* パッケージや、著名なプロバイダーが公開しているサーバーを優先します。出所が不明な MCP サーバーは導入しません。

使わない MCP は削除する

mcpServers に登録した MCP サーバーは Claude Code の起動時に接続を試みます。使っていない MCP を残すと、起動時間の増加・エラーノイズ・攻撃面の拡大につながります。定期的に見直して不要なものを削除します。

実践演習

Step 1: 現在の MCP 設定を確認する

ターミナルでプロジェクトルートに移動し、現在の設定を確認します。

cat .claude/settings.json

mcpServers セクションの有無と、登録されているサーバーの一覧を読み取ります。

✅ 確認: JSON ファイルが表示されれば読み込み成功です。mcpServers セクションがない場合は、次のステップで追加します。

Step 2: GitHub MCP サーバーを追加する

事前に GITHUB_TOKEN 環境変数を設定しておきます。GitHub の「Settings > Developer settings > Personal access tokens」から、repo スコープを持つトークンを発行します。

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

次に .claude/settings.json の mcpServers セクションに以下を追加します。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

✅ 確認: JSON の構文が正しいかを確認します。末尾のカンマや括弧の対応ミスがないかチェックします。

Step 3: Claude Code を再起動して MCP を確認する

Claude Code セッションを一度終了し、再起動します。その後、チャット内で /mcp コマンドを実行します。

/mcp

出力例:

Connected MCP servers:
- github (connected)

✅ 確認: github (connected) と表示されれば、GitHub MCP サーバーへの接続が成功しています。failed to connect などのエラーが表示された場合は、GITHUB_TOKEN 環境変数が正しく設定されているかを確認してください。

Step 4: GitHub MCP の動作を確認する

Claude に次のように依頼して、GitHub MCP が正常に動作することを確認します。

このリポジトリのオープンな PR を一覧表示してください。

Claude が GitHub API を通じてプルリクエストの一覧を取得して回答すれば、MCP の統合は成功です。

✅ 確認: Claude が PR の番号・タイトル・作成者を含むリストを返せば動作確認完了です。「GitHub への接続情報がありません」のような回答が出た場合は、Step 3 で /mcp の表示が connected になっているかを再確認します。

まとめ

MCP（Model Context Protocol）は Claude が外部ツール・データソースと通信するプロトコル
MCP サーバーはローカル（command でプロセス起動）とリモート（url で接続）の 2 種類がある
設定は .claude/settings.json の mcpServers セクションに記述する
API キーは ${VAR_NAME} 形式で環境変数を参照し、ファイルに直接書かない
settings.local.json に個人の認証情報を置き、Git で共有する settings.json とは分ける
不要な MCP は定期的に削除して攻撃面を最小化する

次のステップ

Memory システム設計 — セッションをまたいで情報を保持する Memory の設計方法を学ぶ
ハーネスのテストと検証 — MCP を含む設定全体が意図通りに機能するかを検証する方法へ進む

よくある質問

Q: /mcp コマンドを実行しても何も表示されません。

A: mcpServers セクションが settings.json に存在するか、JSON 構文が正しいかを確認してください。また、Claude Code を再起動しないと設定変更が反映されない場合があります。

Q: npx ではなく別のコマンドで MCP サーバーを起動できますか？

A: できます。command フィールドには node、python、deno など任意の実行ファイルを指定できます。args でスクリプトのパスを渡すことで、自作の MCP サーバーも起動できます。

Q: ローカル MCP とリモート MCP を同時に設定できますか？

A: できます。mcpServers オブジェクトに複数のエントリを追加するだけです。ローカル MCP（command 形式）とリモート MCP（url 形式）を混在させることも問題ありません。

Q: MCP サーバーが起動に失敗した場合、Claude はどう動作しますか？

A: MCP サーバーへの接続に失敗した場合、Claude はそのサーバーの機能を利用せず、通常の会話モードで動作します。/mcp でサーバーのステータスを確認し、エラーが発生しているサーバーの設定を見直してください。

Q: GitHub MCP でアクセスできるリポジトリの範囲は？

A: GITHUB_TOKEN に付与したスコープと、そのトークンが属するアカウントがアクセスできるリポジトリの範囲に依存します。組織のリポジトリにアクセスする場合は、org スコープや SSO 認可が必要な場合があります。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

Anthropic, Claude Code documentation
Anthropic, Claude API documentation

クイズ

Memory システム設計 — ユーザー・プロジェクト・参照メモリの設計指針

Hooks 実装 — ライフサイクルフックで自動化する