はじめに
MCP Toolbox の cloud-storage prebuilt を使うと、AI エージェントから Cloud Storage（GCS）を直接操作できます。prebuilt（事前構築ツール）とは、MCP Toolbox に組み込まれた既成のツールセットのことです。自分でツール定義を書かなくても、--prebuilt cloud-storage の指定だけで Cloud Storage 用のツール一式を利用できます。対象は Codex や Claude Code のような stdio 型の MCP クライアントです。本記事では、読み取り専用の最小権限で Cloud Storage MCP を導入し、実際にオブジェクトを読み取れる状態にするまでの手順と試した結果をまとめます。
本記事のまとめ
toolbox --prebuilt cloud-storage --stdioを MCP サーバーとして登録すると、Codex と Claude Code の両方から GCS を操作できる。- 権限は
roles/mcp.toolUserとroles/storage.objectViewerによる読み取り専用から始めるのが安全である。 read_objectには 8 MiB の上限がある。8 MiB 超のオブジェクトはdownload_objectで取得できることを実際に確認した。- 古い
toolboxバイナリでは prebuilt にcloud-storageが含まれない場合があるため、導入時はバージョン確認が必要になる。
なお、Cloud Storage 向けの MCP には 2 種類あります。本記事が扱うのは、ローカルで実行する MCP Toolbox の cloud-storage prebuilt（stdio 型）です。Google が管理するリモート MCP サーバー（use-cloud-storage-mcp、HTTP 型）は、導入手順と対象形式が異なる別物となるので注意してください。詳細は次のセクションの注意書きで説明します。
MCP Toolbox の Cloud Storage MCP（GCS MCP）でできること・制限
MCP Toolbox の cloud-storage prebuilt では、バケット一覧・オブジェクト一覧・メタデータ取得・オブジェクトの読み取りとダウンロードができます。ただしツールごとに対象データとサイズ制限が異なります。
参考にした公式ドキュメントは、Cloud Storage MCP サーバーを使用するとMCP を使用して LLM を Cloud Storage に接続するです（2026-07-04 時点）。これらの内容と実際に試した結果をもとに、主なツールの制限を整理すると次のとおりです。
| ツール | 対象データ | サイズ制限 | 備考 |
read_object | UTF-8 テキストのみ（バイト範囲指定も可 | 8 MiB（8,388,608 バイト） | バイナリオブジェクトは拒否。8 MiB 超はエラーになることを実際に確認済み |
get_object_metadata | メタデータのみ（内容は転送しない） | 制限の記載なし | – |
list_objects / list_buckets | 一覧情報のみ（内容は転送しない） | 制限の記載なし | – |
download_object | 任意の形式（ローカルファイルに保存） | 制限の記載なし | 8 MiB 超のオブジェクトでも成功することを実際に確認済み |
ファイル形式による可否は公式ドキュメントに明記されています。read_object で読めるのはテキスト系のみで、zip・jpeg・pdf などのバイナリは拒否されます。
注意: Google 管理のリモート Cloud Storage MCP サーバー（use-cloud-storage-mcp）は、上表とは対象範囲が異なります。リモート側は、コンテンツ分析の読み取りをテキスト・PDF・画像に制限しています。公式ドキュメントを読み比べるときは、どちらの MCP の記述かを確認してください。本記事の対象は MCP Toolbox の cloud-storage prebuilt です。
read_object の 8 MiB 上限を実際に試した結果は、設定と動作確認のあとの「8 MiB の上限を実際に試した結果」で紹介します。
導入前に決めること（対象プロジェクト・バケット・権限方針）
導入前に、対象の GCP プロジェクト・対象バケット・権限方針の 3 点を決めておきます。特に権限は、読み取り専用の最小構成から始めることをおすすめします。
Cloud Storage MCP のツール呼び出しには、MCP 呼び出し自体の権限と Cloud Storage の操作権限の両方が必要です。用途別の代表的なロールは次のとおりです。
| 用途 | ロール |
| MCP ツール呼び出し | roles/mcp.toolUser |
| オブジェクト一覧、読み取り、メタデータ取得 | roles/storage.objectViewer |
| オブジェクト書き込み | roles/storage.objectCreator |
| バケット作成、バケット一覧 | roles/storage.admin |
最小権限の考え方は次のとおりです。
- 読み取りだけなら
roles/mcp.toolUserとroles/storage.objectViewerを基本にする。 - 可能ならプロジェクト全体ではなく、対象バケットに絞って IAM を付与する。
- 書き込みやバケット管理のロールは、必要性が明確になってから追加する。
なお、公式ドキュメントによると API キーでの認証はできません。IAM と OAuth 2.0 による認証・認可が必要です。
Codex / Claude Code に Cloud Storage MCP（MCP Toolbox）を設定する
設定の流れは、toolbox バイナリを導入してバージョンを確認し、各クライアントに MCP サーバーとして登録する、という 2 段階です。
まず公式ドキュメントの手順で toolbox バイナリを導入し、バージョンを確認します。
toolbox --version検証時のバージョンは次のとおりです。
toolbox version 1.2.0+binary.darwin.arm64Codex の設定（config.toml）
Codex では ~/.codex/config.toml に MCP サーバーを記述します。パスとプロジェクト ID はご自身の環境に置き換えてください。
[mcp_servers.storage]
command = "/PATH/TO/toolbox"
args = ["--prebuilt", "cloud-storage", "--stdio", "--port", "0", "--log-level", "ERROR"]
[mcp_servers.storage.env]
CLOUD_STORAGE_PROJECT = "PROJECT_ID"Claude Code の設定（claude mcp add）
Claude Code では claude mcp CLI で同じサーバー構成を登録できます。ユーザースコープで登録する場合のコマンドは次のとおりです。
claude mcp add storage -s user -e CLOUD_STORAGE_PROJECT=PROJECT_ID -- /PATH/TO/toolbox --prebuilt cloud-storage --stdio --port 0 --log-level ERROR実際に設定したときにはまった点が 3 つあります。
-e KEY=VALUEは可変長オプションのため、直後にサーバー名などの位置引数を続けると、誤って-eに飲み込まれてエラーになる。- そのため
--でコマンド部分を明示的に区切る必要がある。claude mcp add <name> -s user -e KEY=VALUE -- <command> <args...>の順で指定する。 - 追加した設定は、
claude mcp addの実行時点では実行中のセッションに反映されない。Claude Code を再起動して初めて MCP サーバーが使えるようになる。
バージョンの違いでハマったこと
古い toolbox バイナリを使っていたところ、prebuilt として cloud-storage を利用できませんでした。最新版へ更新し、toolbox --help の prebuilt の許可リストに cloud-storage が含まれることを確認して解決しました。
toolbox --help事実として確認できているのは「バイナリを更新した」「新バージョンで cloud-storage の対応を確認できた」の 2 点です。旧バージョンで発生する事象の詳細までは検証していません。そのため導入時は、最初に toolbox --version と toolbox --help で prebuilt の対応状況を確認することをおすすめします。
読み取り専用で動作確認する
クライアントを再起動して MCP サーバーが認識されたら、読み取り専用の操作で動作確認します。検証では、架空の日次売上データを記録した小さな CSV ファイルを対象バケットに置きました。そのうえで、次のようなプロンプトで読み取りと分析を依頼しました。
GCS MCP を利用して storage-<PROJECT_ID>-gcs-mcp-verification/gcs-mcp-smoke-test.csv を分析してください結果は成功でした。Claude Code が storage MCP サーバーのツールを呼び出して CSV の内容を読み取り、店舗別・商品別・日別の集計と傾向の説明まで返しています。
書き込み系のロールを付与していないため、この状態でできるのは一覧取得・メタデータ取得・読み取りまでです。まず読み取り専用で運用を始めて、書き込みまで任せるかどうかは必要性が明確になってから判断できます。
8 MiB の上限を実際に試した結果
read_object の 8 MiB 上限を超えるとどうなるかを、上限前後のサイズのテキストファイルで試しました。1 つ目は 8 MiB − 1 KiB（8,387,584 バイト）のファイルです。2 つ目は 8 MiB + 1 KiB（8,389,632 バイト）のファイルです。
read_object（8 MiB 未満のテキストファイル） → 成功。全文を取得できた。
read_object（8 MiB 超のテキストファイル） → 失敗。
エラー例: "object is too large to read in one call; narrow the 'range' parameter...
exceeds 8388608 byte limit: cloud storage read size limit exceeded"
download_object（8 MiB 超のテキストファイル） → 成功。
ダウンロードしたファイルは元データと MD5 が一致し、内容の欠落・破損はなかった。
エラーメッセージに上限値 8,388,608 バイト（8 MiB）が明示されており、ちょうど 8 MiB が境目であることを確認できました。次のスクリーンショットは、Claude Code 上で試したときの画面です。
8 MiB という上限は、「AI エージェントが読み取るテキストデータ」の用途なら十分なサイズです。設定ファイルやログ、小〜中規模のデータはこの範囲に収まります。一方で、大きめのデータセットやバイナリを扱いたい場合は download_object でローカルに保存してから処理する、という使い分けになります。
まとめ
MCP Toolbox の cloud-storage prebuilt を使い、Codex と Claude Code から GCS のオブジェクトを読み取れる状態を実現できました。権限は読み取り専用の最小構成です。
- 導入時は
toolboxのバージョンに注意する。--prebuilt cloud-storageが使えるバージョンであることをtoolbox --helpで確認してから設定する。 read_objectには 8 MiB（8,388,608 バイト）の上限がある。超えるオブジェクトはdownload_objectでローカルに保存して処理する。- 権限は
roles/mcp.toolUser+roles/storage.objectViewerの読み取り専用から始める。書き込みやバケット管理のロールは、必要性が明確になってから追加を検討する。
