Claude CodeのMCPサーバー設定 - 外部ツール連携ガイド

Claude CodeにMCP（Model Context Protocol）サーバーを追加し、外部ツールやデータソースと連携するための設定方法をまとめたリファレンス。

MCPとは

MCP（Model Context Protocol）は、AIアシスタントが外部ツールやデータソースにアクセスするための標準プロトコル。Anthropicが提唱するオープン仕様で、以下のような機能を提供する。

概念	説明
Tools	AIが呼び出せる関数（ブラウザ操作、DB検索、API呼び出し等）
Resources	AIが参照できるデータソース（ファイル、ドキュメント等）
Prompts	サーバーが提供する定型プロンプトテンプレート

MCPにより、Claude Codeは標準機能（ファイル読み書き、Bash実行、Web検索等）に加え、任意の外部サービスやツールにアクセスできるようになる。

設定方法の概要

MCPサーバーの設定方法は2つある。

方法	用途
claude mcp add コマンド	CLI上で対話的にサーバーを追加
設定ファイルの直接編集	JSON形式で一括管理

CLIコマンドによる設定

サーバーの追加（claude mcp add）

基本構文:

claude mcp add --transport <type> <name> [options] [-- <command> [args...]]

stdioサーバーの追加

ローカルプロセスとして起動するサーバー。最も一般的な形式。

# 基本形
claude mcp add --transport stdio <name> -- <command> [args...]

# 例: Playwrightサーバー
claude mcp add --transport stdio playwright -- npx -y @anthropic-ai/mcp-playwright

# 例: 環境変数付き
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

-- はClaude Code側のフラグとサーバーコマンドの引数を区切るセパレータ。

HTTPサーバーの追加

リモートで動作するHTTPベースのサーバー。

# 基本形
claude mcp add --transport http <name> <url>

# 例: Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 例: 認証ヘッダー付き
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

SSEサーバーの追加（非推奨）

Server-Sent Eventsベースのサーバー。現在はHTTPトランスポートへの移行が推奨されている。

# 基本形（非推奨）
claude mcp add --transport sse <name> <url>

# 例
claude mcp add --transport sse asana https://mcp.asana.com/sse

スコープの指定

サーバーの適用範囲を --scope オプションで指定できる。

# ローカルスコープ（デフォルト） - 現在のプロジェクトの自分だけ
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# プロジェクトスコープ - チーム全員で共有（.mcp.jsonに保存）
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# ユーザースコープ - 全プロジェクトで使用
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

スコープ	保存先	共有範囲
local	.claude/settings.local.json	自分のみ（gitignore対象）
project	.mcp.json	リポジトリの全メンバー
user	~/.claude/settings.json	自分の全プロジェクト

その他のコマンド

# サーバー一覧の確認（Claude Code内）
/mcp

# サーバーの削除
claude mcp remove <name>

# サーバー一覧（CLI）
claude mcp list

設定ファイルの直接編集

プロジェクトレベル: .mcp.json

プロジェクトルートに .mcp.json を配置し、チーム全体で共有するMCPサーバーを定義する。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-playwright"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    }
  }
}

ユーザーレベル: ~/.claude/settings.json

全プロジェクト共通で使用するサーバーを定義する。

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

ローカルレベル: .claude/settings.local.json

個人の開発環境固有の設定。.gitignore に含まれるため、APIキー等を含む設定に適する。

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "mcp_server_db"],
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/devdb",
        "DB_USER": "dev_user",
        "DB_PASSWORD": "dev_password"
      }
    }
  }
}

サーバータイプの詳細

stdio（標準入出力）

ローカルプロセスとして起動し、stdin/stdoutでJSON-RPCメッセージをやり取りする。

{
  "my-server": {
    "command": "node",
    "args": ["server.js", "--port", "3000"],
    "env": {
      "API_KEY": "${MY_API_KEY}",
      "LOG_LEVEL": "debug"
    }
  }
}

特徴:

• ローカル実行のため高速
• 環境変数でシークレットを安全に渡せる
• NPMパッケージとして配布されるサーバーの大半がこの形式
• Claude Codeが子プロセスとして起動・管理する

注意点:

• サーバープロセスが stdout にMCPメッセージ以外のテキスト（console.log 等）を出力するとJSON-RPCストリームが壊れる
• デバッグログは stderr に出力する必要がある

http（HTTP/Streamable HTTP）

リモートサーバーにHTTPで接続する。SaaSが公式に提供するMCPエンドポイント等で使用。

claude mcp add --transport http notion https://mcp.notion.com/mcp

特徴:

• リモートサーバーとの通信に使用
• 認証ヘッダーをサポート
• SaaSプロバイダーが公式エンドポイントを提供するケースが増加中

sse（Server-Sent Events）- 非推奨

HTTPベースだが、サーバーからクライアントへの通知にSSEを使用する旧方式。新規採用は非推奨で、http トランスポートを使用すべき。

環境変数の扱い

変数の参照構文

環境変数は ${VARIABLE_NAME} 構文でJSON設定内に埋め込める。

{
  "my-server": {
    "command": "python",
    "args": ["-m", "my_mcp_server"],
    "env": {
      "DATABASE_URL": "${DB_URL}",
      "API_KEY": "${API_KEY}",
      "LOG_LEVEL": "info"
    }
  }
}

この場合、DB_URL と API_KEY はシステムの環境変数から解決される。LOG_LEVEL のようにリテラル文字列も直接指定可能。

CLIでの環境変数指定

--env フラグで環境変数を直接指定できる。

claude mcp add --transport stdio \
  --env API_KEY=sk-xxxx \
  --env DB_URL=postgres://localhost/mydb \
  my-server -- python -m my_mcp_server

セキュリティに関する注意

• .mcp.json（project scope）にシークレットを直接記述しない。${VAR} 参照を使い、実際の値はシステム環境変数やシークレットマネージャーで管理する
• ローカル開発用のシークレットは .claude/settings.local.json（local scope、gitignore対象）に記述可能
• チームで共有する .mcp.json には環境変数の参照のみを記述し、READMEに必要な環境変数の一覧を記載する

人気のMCPサーバー

ブラウザ操作

サーバー	パッケージ	用途
Playwright	@anthropic-ai/mcp-playwright	ブラウザの自動操作、スクリーンショット、E2Eテスト
Puppeteer	@anthropic-ai/mcp-puppeteer	Chromiumベースのブラウザ自動化

claude mcp add --transport stdio playwright -- npx -y @anthropic-ai/mcp-playwright

ドキュメント参照

サーバー	パッケージ	用途
Context7	@upstash/context7-mcp	ライブラリの最新ドキュメントを検索・参照
Filesystem	@modelcontextprotocol/server-filesystem	ローカルファイルの読み書き

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

SaaS連携

サーバー	パッケージ / URL	用途
GitHub	@modelcontextprotocol/server-github	Issue/PR操作、リポジトリ管理
Slack	@anthropic-ai/mcp-slack	チャンネル操作、メッセージ送信
Notion	https://mcp.notion.com/mcp (HTTP)	ページ操作、データベース検索
Stripe	https://mcp.stripe.com (HTTP)	決済情報の参照・操作
Linear	@anthropic-ai/mcp-linear	プロジェクト管理、Issue操作

# GitHub（環境変数でトークンを渡す）
claude mcp add --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN \
  github -- npx -y @modelcontextprotocol/server-github

# Notion（HTTPトランスポート）
claude mcp add --transport http notion https://mcp.notion.com/mcp

データベース

サーバー	パッケージ	用途
PostgreSQL	@modelcontextprotocol/server-postgres	PostgreSQLへのクエリ実行
SQLite	@modelcontextprotocol/server-sqlite	SQLiteデータベース操作

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

その他

サーバー	パッケージ	用途
Memory	@modelcontextprotocol/server-memory	会話をまたいだ知識の永続化
Fetch	@anthropic-ai/mcp-fetch	Webページの取得・スクレイピング

設定の完全な例

プロジェクトの .mcp.json に複数サーバーを設定する実用的な例:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-playwright"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

トラブルシューティング

サーバーが起動しない

確認項目	対処法
コマンドが存在するか	which <command> でパスを確認
ファイルパスが正しいか	絶対パスで指定する
実行権限があるか	chmod +x <file> で権限を付与
Node.jsのバージョン	MCPサーバーの多くはNode.js 18以上を要求

# デバッグログを有効にして起動
claude --debug

通信エラーが発生する

stdioサーバーでJSON-RPCの通信が失敗する主な原因:

• stdout汚染: サーバープロセスが console.log() や print() で標準出力にデバッグメッセージを出力している。MCP通信はstdoutを使うため、余計な出力があるとJSON-RPCストリームが壊れる
  • 対処: デバッグ出力は stderr（console.error() や sys.stderr）に変更する
• JSON-RPCフォーマット不正: サーバーが返すレスポンスがJSON-RPC仕様に準拠していない
  • 対処: MCP SDKを使用してサーバーを実装する

サーバーが認識されない

# 登録済みサーバーの確認
claude mcp list

# Claude Code内で確認
/mcp

• 設定ファイルのJSONが正しいか（末尾カンマ等の構文エラーがないか）確認する
• スコープが意図通りか確認する（別プロジェクトで追加したlocalスコープのサーバーは現在のプロジェクトからは見えない）

環境変数が解決されない

• ${VAR} 構文で参照した変数がシステム環境変数として設定されているか確認する
• シェルの設定ファイル（.bashrc / .zshrc）で export しているか確認する
• Claude Codeを再起動して環境変数の変更を反映させる

よくあるエラーメッセージ

エラー	原因	対処
spawn ENOENT	コマンドが見つからない	パスの確認、npx で実行する場合は -y フラグを付ける
connection refused	リモートサーバーに接続できない	URLの確認、ファイアウォール設定の確認
401 Unauthorized	認証エラー	APIキー・トークンの確認、--header での認証設定
timeout	サーバーの応答が遅い	ネットワーク確認、サーバー側のログ確認

参考リンク

• Claude Code 公式ドキュメント - MCP - MCPサーバーの設定方法に関する公式リファレンス
• Model Context Protocol 仕様 - MCPプロトコルの仕様書・サーバー一覧
• MCP Servers リポジトリ - 公式・コミュニティ製MCPサーバーの一覧
• Claude Code 公式ドキュメント - Claude Code全般のドキュメント