.mcp.json で環境変数からトークンを渡す書き方(${VAR} 展開)

.mcp.json はチームで共有するために Git にコミットするファイルです。ここに GitHub のアクセストークンを直接書くと、リポジトリを見られる全員に漏れます。Claude Code は .mcp.json の中で ${環境変数名} の形で環境変数を参照できるので、トークンの実体はシェル側に置きます。

書き方

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_MCP_URL:-https://mcp.example.internal/mcp}",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

記法	意味
${GITHUB_TOKEN}	環境変数 GITHUB_TOKEN の値に置き換わる
${VAR:-既定値}	VAR が未設定なら既定値を使う

展開は env だけでなく、command、args、url、headers の値でも使えます。

環境変数の置き場所

# ~/.zshrc または ~/.bashrc
export GITHUB_TOKEN="ghp_xxxxxxxx"

シェルの設定ファイルに書いておくと、ターミナルから claude を起動したときに読まれます。VS Code 拡張から使う場合は、VS Code 自体がその環境変数を持っている必要があるため、シェルの設定ファイルに書いたうえで VS Code を再起動するか、ターミナルから code . で起動してください。

direnv を使っているプロジェクトなら、.envrc に書いてディレクトリ単位で切り替えられます(.envrc は .gitignore に入れます)。

未設定時の確認

環境変数が設定されていないと、サーバーは起動するものの認証に失敗します。

1. /mcp でサーバーの状態を確認する。「failed」なら次へ
2. ターミナルで echo $GITHUB_TOKEN を実行し、値があるか確認する
3. Claude Code を起動したシェルと、環境変数を設定したシェルが同じか確認する
4. .mcp.json の変数名のスペルを確認する

チームでの運用ルール

• .mcp.json には ${VAR} だけを書き、値は絶対に書かない
• README に「必要な環境変数の一覧」を載せる(名前だけ。値は各自が発行)
• .env.example にも同じ名前を並べておく
• トークンの権限は最小限にする(GitHub なら読み取り専用のスコープから始める)

関連する記事

MCP サーバーの追加方法とスコープの違いは、親記事の Claude Code に MCP サーバーを追加する方法 を参照してください。秘密情報全般の扱いは AI コーディングツールに秘密情報を読ませないための設定 にまとめています。

まとめ

• .mcp.json では ${GITHUB_TOKEN} の形で環境変数を参照し、値は書かない
• ${VAR:-既定値} で未設定時の既定値を指定できる。env、args、url、headers で使える
• 環境変数はシェルの設定ファイルに置き、VS Code から使う場合は再起動して反映する
• 誤ってコミットしたら、まずトークンを失効させる