Claude Code の MCP 設定をチームで共有する方法（.mcp.json の活用）

Claude Codeに登録したMCPサーバーの設定は、.mcp.jsonというファイルを用いてチームメンバーと共有できます。当サイトの「Claude Code に MCP サーバーを接続する設定方法」で扱った天気予報MCPサーバーを題材に、チーム共有のための設定方法をハンズオン形式でご紹介します。

本記事では以下のことを実施します。

天気予報MCPサーバーをprojectスコープで登録し、.mcp.jsonを生成する。
環境変数を使用して、別ユーザーでも動作するように.mcp.jsonを編集する。
APIキーやトークンを安全に扱う方法を学ぶ。
機密情報がGitリポジトリにコミットされないようにする。
.mcp.jsonをGitリポジトリにコミットし、チームメンバーが利用できる状態を作る。

前提環境

本記事では、以下のツールがインストール済みであることを前提としています。

Claude Code（Claude Code CLIの導入と基本操作（Windows））
Python 3.10 以上
uv（uvのインストールと使い方（pyenvよりも高速）－ Python環境構築）
Git

本記事の動作確認は2026年5月時点、Claude Code v2.x 系を想定しています。

サーバーの準備

本記事では、当サイトの「Claude Code に MCP サーバーを接続する設定方法」で扱った天気予報MCPサーバーを題材とします。すでに前の記事で天気予報MCPサーバーを準備し、local スコープで登録済みの方は、以下のコマンドでMCPサーバーの登録のみを削除してから、本セクションを読み飛ばしてください。

claude mcp list # サーバーの一覧を確認
claude mcp remove weather # サーバー名(weather)は実際に用いた名前に変更

天気予報MCPサーバーの準備がまだの場合は、以下の手順で準備します。サンプルコードはgithubで公開されています。

git clone --filter=blob:none https://github.com/modelcontextprotocol/quickstart-resources.git
cd quickstart-resources/weather-server-python/
uv sync

これで天気予報MCPサーバーの準備は完了です。サーバーは、get_alerts（米国の州コードから気象警報を取得）と get_forecast（緯度経度から天気予報を取得）の2つのツールを提供します。

project スコープと .mcp.json の概要

まず、project スコープの位置づけと、.mcp.json の基本的な仕組みを整理します。

Claude Code の3つのスコープ

Claude Code のMCP設定には、設定の保存場所と適用範囲を決める「スコープ」という概念があります。スコープは以下の3種類です。

スコープ	保存先	適用範囲	チーム共有
local （デフォルト）	`~/.claude.json` （プロジェクト別エントリ）	自分のみ、当該プロジェクトのみ	しない
project	プロジェクト直下 `.mcp.json`	全員、当該プロジェクトのみ	する（Gitコミット）
user	`~/.claude.json` （共通エントリ）	自分のみ、全プロジェクト	しない

local と user は、いずれも個人のホームディレクトリ配下にある ~/.claude.json に保存されるため、他のメンバーには共有されません。一方、project スコープで登録すると、設定はプロジェクト直下の .mcp.json という独立したファイルに書き出され、Git にコミットしてリポジトリと一緒に共有できる状態になります。

同名のMCPサーバーが複数のスコープに存在する場合、高優先度のスコープが低優先度のスコープを上書きします。優先順位は個人設定（Local）＞チーム共有設定（Project）＞全プロジェクト共有設定（User）の順です。例えば、同名のサーバーがLocalとProjectの両方のスコープに登録されている場合、Localの優先度が高いため、.mcp.jsonの中のそのサーバーの設定は完全に無視されて~/.claude.jsonの設定が使用されます。

.mcp.jsonファイル

.mcp.jsonは、プロジェクトのルートディレクトリに配置される設定ファイルです。Claude Code はプロジェクトディレクトリで起動した際に、自動的にこのファイルを読み込みます。

ファイルの構造はJSON形式です。MCPサーバーを手元で動かす場合はトランスポートはstdioです。この場合、.mcp.jsonは以下のような構造になっています。

{
  "mcpServers": {
    "<サーバー名>": {
      "type": "stdio",
      "command": "<サーバーの起動コマンド>",
      "args": ["<引数1>", "<引数2>"],
      "env": {
         "<変数名>":"<値>"
      }
    }
  }
}

より詳しい説明は、後述の「.mcp.jsonの中身を読む」で行います。

チーム共有の流れ

.mcp.jsonを用いたチーム共有は以下のような流れになります。

プロジェクトのリーダーや初期メンバーがcluade mcp add --scope projectなどでMCPサーバーを登録する。
プロジェクト直下に.mcp.jsonが生成される。
.mcp.jsonをgit addしてリポジトリにコミットする。
他のメンバーがリポジトリをgit cloneして、プロジェクトディレクトリでClaude Codeを起動する。
初回起動時に.mcp.jsonの内容を承認するプロンプトが表示される。
承認後、.mcp.jsonに記述されたMCPサーバーが自動的に利用可能になる。

この流れにより、メンバー全員が同じMCPサーバー構成で開発を進められます。

共有時に注意すること

.mcp.jsonをGitにコミットして共有する際に以下の2点を注意します。

注意点１：環境依存の情報を直書きしない

.mcp.jsonには、各メンバーの環境で異なる値（ホームディレクトリの絶対パスなど）を直接書き込まないようにします。直書きすると、他のメンバーの環境では動作しません。代わりに環境変数を経由して値を渡す方法がありますので、それを使用します。

注意点２：機密情報をコミットしない

.mcp.jsonはGitリポジトリにコミットされるため、APIキーやアクセストークン、パスワードといった機密情報やユーザー名などの個人情報を直接書き込むと、リポジトリのアクセス権を持つ全員に共有された上で、コミット履歴にも残ってしまいます。これらの情報は環境変数で外部化し、.mcp.jsonには参照（${API_KEY}など）のみを書く運用が推奨されます。

天気予報MCPサーバーをprojectスコープで登録する

天気予報MCPサーバーをprojectスコープで登録します。これにより、プロジェクト直下に.mcp.jsonが生成されます。Localスコープに同名サーバーが登録されている場合はそちらが優先されるため、本記事の冒頭に書いているとおり、登録をあらかじめ解除しておきます。

projectスコープで登録する

--scope project オプションを付けて weather サーバーを登録します。プロジェクトディレクトリで実行することがポイントです。

weather-server-python ディレクトリに移動した上で、claude mcp add コマンドを実行します。

claude mcp add --scope project --transport stdio weather -- uv --directory /home/<ユーザー名>/quickstart-resources/weather-server-python run weather.py

ディレクトリのパスは環境に応じて変更してください。オプションの意味は次の通りです。

要素	意味
--scope project	プロジェクトスコープを指定
--transport stdio	トランスポートとして stdio を指定
weather	登録するサーバー名
--	オプションと起動コマンドの区切り
uv --directory … run weather.py	起動コマンド

インターネット上ではなく手元で動かすのでトランスポートにstdioを使用します。また、起動コマンドで--directoryを用いることでuvのプロジェクトディレクトリを指定して、どこからClaude Codeを実行しても同じ動作をするようにしています。

Windowsネイティブで動かす場合、環境によってはuv や npx などのコマンドが Claude Code から直接見つからず、サーバーの起動に失敗するケースがあります。その場合は、起動コマンドの先頭に cmd /c を挟むと解決することがあります。

PowerShell の場合は、パスを引用符””で囲むと安全です。

.mcp.jsonの生成を確認する

登録が完了すると、プロジェクト直下に.mcp.jsonというファイルが生成されます。ファイルの中身を確認すると、以下のようになっています。ディレクトリパスは登録時の指定したパスとなります。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/home/<ユーザー名>/quickstart-resources/weather-server-python",
        "run",
        "weather.py"
      ],
      "env": {}
    }
  }
}

登録状況を確認する

まず、プロジェクトフォルダでClaude Codeを実行します。

claude

そうすると、自動的にプロジェクトフォルダにある.mcp.jsonファイルを読み込もうとします。初めての場合には承認の確認が行われます。悪意のあるリポジトリへの対策として承認の仕組みが組み込まれています。内容を確認した上で承認してください。

対話モードから一旦抜けて、weather サーバーが project スコープに登録されたことを確認します（対話モードの/mcpでも確認可能）。

claude mcp list

次にサーバーの詳細情報を確認します。スコープがprojectと表示されていることを確認します。

claude mcp get weather

スコープがprojectの場合は、Scope: Project config (shared via .mcp.json)と出力されます。以上で、意図したとおりに登録されていることを確認できました。

認証情報のリセット

承認で拒否した場合には、以降MCPサーバーが検出されません。またリセットするまで認証メッセージも発生しません。認証をすべてリセットする場合には、プロジェクトフォルダで次のコマンドを実行します。

claude mcp reset-project-choices

バージョンによって動作しない場合があることがGitHubで報告されているため、認証情報がリセットされなかった場合はプロジェクトフォルダの.claude/settings.local.jsonを修正します。対象のサーバー名（weather）を削除し、（書かれていれば）enableAllProjectMcpServersをfalseに設定すれば、再度承認メッセージが表示されます。

動作確認

weather サーバーが正しく動作することを確認します。プロジェクトディレクトリで Claude Code を起動します。

claude

試しに、前編と同様に天気予報を問い合わせてみます。

カリフォルニア州の現在の気象警報を教えてください

get_alerts ツールが呼び出され、警報情報が返ってくれば、project スコープでの登録は完了です。

.mcp.jsonの中身を読む

`.mcp.json` の基本構造

前述のとおり、生成された .mcp.json は、おおむね以下のような構造になっています。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/home/<ユーザー名>/quickstart-resources/weather-server-python",
        "run",
        "weather.py"
      ],
      "env": {}
    }
  }
}

mcpServers の下に、登録したいMCPサーバーをサーバー名をキーとして並べる構造です。複数のサーバーを共有したい場合は、mcpServers の下にエントリを追加していきます。各フィールドの意味は以下の通りです。

フィールド	説明
type	トランスポート種別を指定する。stdio / http / sse のいずれか
command	サーバーを起動する実行ファイルの名前または絶対パス
args	`command` に渡す引数の配列
env	サーバー起動時に渡す環境変数（キーと値のオブジェクト）

stdio トランスポートの場合は command と args が必要です。HTTP トランスポートの場合は command と args の代わりに url と headers を使用します（HTTP トランスポートは別記事で扱います）。env は空のオブジェクトになっていますが、サーバーに渡したい環境変数がある場合には、以下のように記述します。

"env": {
  "API_KEY": "your-api-key",
  "DEBUG": "true"
}

APIキーなどを必要とするサーバーでは、ここに環境変数を記述します。

複数サーバーを登録した場合の構造

複数サーバーを登録した場合には、mcpServersの下に複数のサーバーが並びます。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "...", "run", "weather.py"],
      "env": {}
    },
    "notification": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "...", "run", "notification.py"],
      "env": {}
    }
  }
}

~/.claude.json との構造の違い

local スコープと user スコープで使用される ~/.claude.json は、.mcp.json よりも複雑な構造になっています。~/.claude.json には MCP 設定以外のClaude Code 全体の設定も含まれており、概略は以下のようになっています。

{
  "projects": {
    "/path/to/project-a": {
      "mcpServers": {
        "local-server-1": { ... }
      }
    },
    "/path/to/project-b": {
      "mcpServers": {
        "local-server-2": { ... }
      }
    }
  },
  "mcpServers": {
    "user-server": { ... }
  }
}

projects の下にある各プロジェクトパスのエントリには、そのプロジェクトに紐づく local スコープのMCPサーバーが格納されます（例ではlocal-server-1とlocal-server-2）。トップレベルの mcpServers には、すべてのプロジェクトで共通して使用される user スコープのMCPサーバーが格納されます（例ではuser-server）。

スコープと保存先、構造を以下の表に整理します。.mcp.json は MCP 設定だけを記述するシンプルな構造であり、Git にコミットして共有することを前提とした設計になっています。

スコープ	保存先	構造
local	`~/.claude.json`	`projects` 配下のプロジェクトパス別エントリ
project	プロジェクト直下の `.mcp.json`	トップレベルの `mcpServers`
user	`~/.claude.json`	トップレベルの `mcpServers`

直接編集する場合

.mcp.json はテキストエディタで直接編集することも可能です。.mcp.json は標準的な JSON 形式です。JSON は JavaScript と異なり、末尾カンマを許容しません。例えば、以下は構文エラーになります。"command": "uv", の末尾カンマがエラーの原因です。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
    }
  }
}

JSON 形式はコメントをサポートしません。//や/**/などを記述するとエラーが発生します。実際にClaude Codeを起動すると以下のようなエラーが表示されます。

[Error] MCP config is not a valid JSON

また、.mcp.json を直接編集した変更は、Claude Code を再起動するまで反映されません。実行中のセッションを終了し、再度 claude コマンドで起動して反映を確認します。

.mcp.jsonに環境変数を用いる

環境変数の導入

先ほど生成された.mcp.jsonにはホームディレクトリの絶対パスが直接書き込まれています。これだとチームで共有した場合に他のメンバーの環境では動作しません。

Claude Code は .mcp.json 内で ${VAR} 形式の環境変数展開をサポートしています。.mcp.json を読み込む際、${WEATHER_SERVER_DIR} のような記述は、Claude Code 起動時のシェルの環境変数 WEATHER_SERVER_DIR の値で置き換えられます。この機能を用いて.mcp.jsonの環境依存の情報を環境変数で置換します。

.mcp.json をテキストエディタで開き、絶対パスの部分を ${WEATHER_SERVER_DIR} に書き換えます。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${WEATHER_SERVER_DIR}",
        "run",
        "weather.py"
      ],
      "env": {}
    }
  }
}

claude mcp addの実行に注意

.mcp.json を上記のように書き換えた後、同じプロジェクトで再度 claude mcp add --scope project などのコマンドを実行すると、既存の ${VAR} が展開された実値に書き換えられてしまうことがあるという問題が報告されています。これにより、せっかく可搬にした設定が再び環境固有のパスに戻ってしまいます。対処法として、.mcp.json を可搬な形式に編集した後は、できるだけ手動編集で更新するか、変更後に git diff .mcp.json で意図しない書き換えが起きていないか確認することをおすすめします。

使用する環境変数はそれぞれのユーザーが登録しておきます。WSLの場合は以下のコマンドで登録します。

export WEATHER_SERVER_DIR=/home/<ユーザー名>/quickstart-resources/weather-server-python

PowerShellの場合は以下のコマンドで登録します。

$env:WEATHER_SERVER_DIR = "C:\Users\<ユーザー名>\quickstart-resources\weather-server-python"

恒久的に登録する場合はそれぞれに合わせた登録を行ってください。例えば、WSLの場合には~/.bashrcや~/.zshrcに、PowerShellの場合はプロファイル（$PROFILE）に上記のコマンドを書き込みます。これによりターミナル起動時に環境変数が設定されます。

システム全体の環境変数として登録する場合は、スタートメニューから「環境変数を編集」を開き、WEATHER_SERVER_DIR を登録します。設定後、コマンドプロンプトや PowerShell を再起動して反映させます。

動作確認

環境変数を設定した上で、Claude Code を再起動して動作を確認します。

claude

対話モードで /mcp コマンドを実行し、weather サーバーが connected 状態になっていることを確認します。

/mcp

weather サーバーが接続できていれば、${WEATHER_SERVER_DIR} が正しく展開されています。試しに天気予報を問い合わせて、動作を最終確認します。

カリフォルニア州の現在の気象警報を教えてください

正常に応答が返ってくれば、可搬な設定への書き換えは完了です。

環境変数が設定されていない場合の挙動

環境変数 WEATHER_SERVER_DIR を設定せずに Claude Code を起動した場合、サーバーの起動コマンドは uv --directory '' run weather.py のような形になります（あるいは ${WEATHER_SERVER_DIR} が空文字列のまま渡される）。結果として、サーバーは正常に起動できず、/mcp コマンドで確認すると failed 状態になります。

チームで共有したときのために、READMEに必要な環境変数とその設定例を記載しておくことが推奨です。

## MCP サーバーの利用

本リポジトリは天気予報MCPサーバーの設定を `.mcp.json` で共有しています。
利用するには、以下の環境変数を設定してください。

- WEATHER_SERVER_DIR：weather-server-python ディレクトリの絶対パス

機密情報の取り扱い

.mcp.jsonには直書きしない

.mcp.jsonはgitにコミットして共有することを前提とした設計です。このため、APIキーやトークンなどの機密情報は漏洩リスクがあるため、.mcp.jsonに書き込んではいけません。具体的には、

リポジトリのアクセス権を持つ全員にトークンが共有されてしまう。
過去のコミット履歴にトークンが残り続け、後から削除しても完全には消えない。
パブリックリポジトリにpushした場合は、不特定多数に流出する。

などです。間違えて一度でもpushしてしまった場合は、すでに全体に公開されたものとしてAPIキーやトークンなどの情報の変更（再発行）を行う必要があります。

環境変数設定の注意点

仮にAPIキーが必要なMCPサーバーがあった場合、.mcp.jsonは以下のような記述になります。

{
  "mcpServers": {
    "some-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "API_KEY": "${SOME_API_KEY}"
      }
    }
  }
}

環境変数を設定する方法として2つの方法をご紹介します。この他には専用のシークレット管理サービス（AWS Secrets Manager, Azure Key Vaultなど）を使う方法もあり、安全性についてはそちらがより優れています。

方法１：.bashrcなどに書き込む

機密情報となる環境変数を登録する場合、シェルの履歴に残さないことが重要です。コマンドラインで直接設定すると、シェルの履歴ファイル（~/.bash_historyなど）に機密情報が残ってしまいます。このため、.bashrcのような設定ファイルに直接書き込み、機密情報を書き込んだ設定ファイルは、他のユーザーから読めないようにファイル権限を制限します。

chmod 600 ~/.bashrc

機密情報を環境変数として設定した端末は、他人と共有しないようにします。端末を共有してしまうとecho ${VAR}で確認できてしまいます。

方法２：.envを使用する

シェルの設定ファイルに直接書く以外に、プロジェクトごとに .env ファイルで環境変数を管理する方法もあります。.env ファイルとは、環境変数を KEY=VALUE の形式で記述したテキストファイルで、開発プロジェクトでの標準的な手法です。

# .env
SOME_API_KEY=KEY_123456

.env ファイルを Claude Code 起動時に読み込ませる方法はいくつかありますが、シンプルな方法は dotenv-cli のようなラッパーコマンドを利用することです（npxは使用しているプラットフォームに別途インストールしておく必要があります）。

npx dotenv-cli -- claude

このコマンドは、現在のディレクトリの .env ファイルを読み込んで環境変数として設定した上で、claude コマンドを実行します。

また、メンバーが何を設定すべきか把握できるように、空の値を持つ .env.example をリポジトリに含めると便利です。

# .env.example
SOME_API_KEY=

チームのメンバーは、リポジトリをcloneした後に、.env.exampleを.envにコピーし、具体的な値を埋めて運用します。.env ファイルには環境変数の実値が記述されるため、Git リポジトリに含めてはいけません。.gitignore に .env を追加します。

# .gitignore
.env
.env.local
.env.*.local

.mcp.json は共有が目的なのでコミット対象に含めますが、その中身に ${VAR} 形式以外でトークンが書かれていないか、コミット前に確認します。

Gitリポジトリへの追加

天気予報MCPサーバーのための.mcp.jsonとして以下を用います。

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${WEATHER_SERVER_DIR}",
        "run",
        "weather.py"
      ],
      "env": {}
    }
  }
}

テスト用にgithubにリポジトリをあらかじめ作成しておき、.mcp.jsonをpushします。

git clone XXX # XXXはリポジトリのアドレス
git add .mcp.json
git commit -m "Add weather MCP server configuration"
git push origin main

その後に、プロジェクトフォルダを新しく作り直して、リポジトリからクローンします。

git clone XXX # XXXはリポジトリのアドレス

環境変数を設定して、プロジェクトフォルダからClaude Codeを開いて、/mcpスラッシュコマンドで天気予報MCPサーバーが起動しているかを確認します。

claude
/mcp

weather サーバーが接続できていれば、正しく動作しています。

なお、.mcp.json に書かれているのはMCPサーバーの起動コマンドと引数だけであり、サーバーの実体（ソースコードや依存パッケージ）は含まれません。本記事の天気予報MCPサーバーの場合、各メンバーは別途 quickstart-resources リポジトリを clone し、uv sync で依存パッケージを準備しておく必要があります。npx -y で取得できる npm パッケージ型のサーバーや、HTTP トランスポートでリモートホストされているサーバーであれば、この準備が不要または最小限になります。

まとめ

本記事では、Claude Code に登録したMCPサーバーの設定をチームメンバーと共有する方法を、ハンズオン形式で扱いました。要点は以下の通りです。.mcp.json を Git にコミットして共有する際の運用ポイントは以下の通りです。

claude mcp add --scope project ... でMCPサーバーを再登録する。
生成された.mcp.jsonを確認し、環境依存のパスや機密情報を環境変数${VAR}の形式に書き直す。
環境変数をシェルの設定ファイルや.envファイルに登録する。
.gitignoreを整備して、.envなどの機密情報がpushされないようにする。
push前に、.mcp.jsonに機密情報が書き込まれていないことを確認してからリポジトリにpushする。

.env.exampleに空の環境変数リストを作っておき、環境変数の概要をコメントやREADMEに書き込んでおくと使いやすくなります。

Claude Code の MCP 設定をチームで共有する方法（.mcp.json の活用）

目次

サーバーの準備

project スコープと .mcp.json の概要

Claude Code の3つのスコープ

.mcp.jsonファイル

チーム共有の流れ

共有時に注意すること

天気予報MCPサーバーをprojectスコープで登録する

projectスコープで登録する

.mcp.jsonの生成を確認する

登録状況を確認する

動作確認

.mcp.jsonの中身を読む

.mcp.json の基本構造

複数サーバーを登録した場合の構造

~/.claude.json との構造の違い

直接編集する場合

.mcp.jsonに環境変数を用いる

環境変数の導入

動作確認

機密情報の取り扱い

.mcp.jsonには直書きしない

環境変数設定の注意点

Gitリポジトリへの追加

まとめ

`.mcp.json` の基本構造