Zenn
Open5

ClaudeCode MCPのスコープ設定について

Model Context Protocol
setting
調査メモ
Claude Code
kwGkwG

注意書き
2025/08/14時点でのまとめなので､今後仕様が変更になる可能性は大いにあります｡
その都度､最新の情報を公式のページより参照してください｡

目的
複数のプロジェクトでClaudeCodeを使用するシーンが登場してきており､それぞれプロジェクト固有の設定をもつMCPや､個人的にツールとして使用するMCPなどの設定が混在している｡
どのプロジェクトでも便利ツールとしてのMCPは設定レスでシームレスに使えるようにしたいし､プロジェクト固有のものに関しては､プロジェクトごとの設定を保持しつつ､他のプロジェクトメンバーも簡単につかえるものであってほしい｡

公式
https://docs.anthropic.com/en/docs/claude-code/mcp

kwGkwG

適切なスコープの選択

以下に基づいてスコープを選択してください：

  • ローカルスコープ: 個人的なサーバー、実験的な設定、または1つのプロジェクトに固有の機密認証情報
  • プロジェクトスコープ: チーム共有サーバー、プロジェクト固有のツール、またはコラボレーションに必要なサービス
  • ユーザースコープ: 複数のプロジェクトで必要な個人的なユーティリティ、開発ツール、または頻繁に使用するサービス

スコープ階層と優先順位

MCPサーバー設定は明確な優先順位階層に従います。同じ名前のサーバーが複数のスコープに存在する場合、システムはローカルスコープのサーバーを最初に優先し、次にプロジェクトスコープのサーバー、最後にユーザースコープのサーバーという順序で競合を解決します。この設計により、必要に応じて個人的な設定が共有設定を上書きできることが保証されます。

kwGkwG

.mcp.jsonでの環境変数展開

Claude Codeは.mcp.jsonファイルでの環境変数展開をサポートしており、チームがマシン固有のパスやAPIキーなどの機密値に対する柔軟性を維持しながら設定を共有できます。

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

  • ${VAR} - 環境変数VARの値に展開
  • ${VAR:-default} - VARが設定されている場合はその値に、そうでなければdefaultに展開

展開場所: 環境変数は以下で展開できます：

  • command - サーバー実行可能ファイルのパス
  • args - コマンドライン引数
  • env - サーバーに渡される環境変数
  • url - SSE/HTTPサーバータイプの場合
  • headers - SSE/HTTP サーバー認証の場合

変数展開を使用した例:

Copy

{
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

必要な環境変数が設定されておらず、デフォルト値もない場合、Claude Codeは設定の解析に失敗します。

kwGkwG

SerenaMCPの場合

userスコープでのSerenaインストールと各プロジェクトでの起動

1. userスコープでのインストール 

# userスコープでSerenaをインストール（全プロジェクトで利用可能）
claude mcp add serena -s user -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server

2. 各プロジェクトでの起動・アクティベーション方法

方法A: Claude Codeでのチャット指示 

# プロジェクトディレクトリに移動
cd /path/to/your/project

# Claude Codeを起動
claude

# チャットでプロジェクトをアクティベート
"Serenaでこのプロジェクト（$(pwd)）をアクティベートしてください"
# または
"activate_project ツールを使って現在のディレクトリをアクティブなプロジェクトに設定して"

方法B: 直接的なアクティベーション指示 

cd /path/to/your/project
claude

# より具体的な指示
"Serenaのactivate_projectツールを使って、/absolute/path/to/your/projectをアクティベートしてください"

方法C: プロジェクト名での指定 

# 一度アクティベートしたプロジェクトは名前で参照可能
claude

"Serenaで'my-project'という名前のプロジェクトをアクティベートして"

3. 設定確認 

# MCPサーバーの状態確認
/mcp

# または
claude mcp list -s user

4. プロジェクトごとの自動化（オプション）

各プロジェクトに設定ファイルを作成して自動化：

# プロジェクトルートに設定作成
mkdir -p .claude
cat > .claude/project_init.md << EOF
# プロジェクト初期化

このプロジェクトを開始する際は：
1. Serenaでプロジェクトをアクティベート: \`$(pwd)\`
2. プロジェクト固有の設定を確認
EOF

5. 確認コマンド 

# アクティブなプロジェクトを確認
"Serenaで現在アクティブなプロジェクトを教えて"

# 利用可能なプロジェクト一覧
"Serenaで利用可能なプロジェクトをリストして"

利点:

  • 一度のインストールで全プロジェクトで利用可能
  • プロジェクトごとに最適化された動作
  • チーム設定に影響しない個人設定
# userスコープでSerenaをインストール（全プロジェクトで利用可能）
claude mcp add serena --scope user -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server
kwGkwG

GithubMCPの場合

設定はプロジェクトごとに行って共有したいけど､トークンはそれぞれプロジェクトで別々に管理できるようにしたい｡

概要

  • GitHub MCP: プロジェクトスコープで共有
  • 環境変数: direnvで個別管理
  • チーム共有: 設定ファイルのみ、認証情報は個人管理

事前準備

1. direnvインストール

# macOS
brew install direnv

# Ubuntu/Debian
sudo apt install direnv

# その他Linux
curl -sfL https://direnv.net/install.sh | bash

2. シェル設定

# Zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

# Fish
echo 'direnv hook fish | source' >> ~/.config/fish/config.fish

プロジェクトセットアップ手順

1. プロジェクトにGitHub MCP追加

# プロジェクトルートで実行
claude mcp add github -s project -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

2. 環境変数テンプレート作成

# .envrc.template（Git管理対象）
export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_token_here"
export GITHUB_ORGANIZATION="your-org-name"
export GITHUB_USERNAME="your-github-username"

3. .gitignore設定

# .gitignore
.envrc
.env.local

4. 個人環境変数設定

# テンプレートをコピー
cp .envrc.template .envrc

# 実際のトークンを設定
# .envrc
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_actual_token"
export GITHUB_ORGANIZATION="your-org"
export GITHUB_USERNAME="your-username"

# direnvに許可
direnv allow

5. README.mdにセットアップ手順追加

## 開発環境セットアップ

### 前提条件
- Claude Code がインストール済み
- Docker がインストール済み

### 手順

1. **direnvインストール**
   ```bash
   # macOS
   brew install direnv
   
   # Ubuntu/Debian
   sudo apt install direnv

  1. シェル設定

    # Zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

  2. 環境変数設定

    cp .envrc.template .envrc
# .envrcを編集してGitHubトークンを設定
direnv allow

  3. Claude Code起動

    claude

GitHubトークン取得方法

  1. GitHub → Settings → Developer settings → Personal access tokens
  2. "Generate new token (classic)" を選択
  3. repo 権限を付与
  4. 生成されたトークンを .envrc に設定

ファイル構成

project/ ├── .mcp.json # ← チーム共有（Git管理） ├── .envrc.template # ← テンプレート（Git管理） ├── .envrc # ← 個人設定（Git管理外） ├── .gitignore # ← .envrcを除外 └── README.md # ← セットアップ手順

動作確認

# ディレクトリに入ると自動で環境変数設定
cd project/
# direnv: loading ~/project/.envrc
# direnv: export +GITHUB_PERSONAL_ACCESS_TOKEN +GITHUB_ORGANIZATION +GITHUB_USERNAME

# 環境変数確認
echo $GITHUB_PERSONAL_ACCESS_TOKEN

# Claude Code起動
claude

# MCP確認
/mcp

メリット

  • ✅ チーム全体で同じMCP設定
  • ✅ 個人の認証情報は秘匿
  • ✅ 新メンバーも簡単セットアップ
  • ✅ ディレクトリ移動で自動切り替え
  • ✅ 環境変数漏洩リスク軽減