gcs

GCS MCP サーバー

きめ細かなツールアクセス制御を備えた、Google Cloud Storage 操作用の MCP サーバーです。GCS バケットとオブジェクトの読み取り／書き込み操作に対応し、セキュリティと権限管理のためのツールグループを設定できます。

主な特長

• GCS バケットとオブジェクトの包括的な管理（一覧表示、取得、アップロード、コピー、削除）
• ツールグループ（readonly、readwrite、delete）によるきめ細かなアクセス制御
• 環境変数による個別ツールの有効化／無効化
• 複数の認証方式（サービスアカウントキーファイル、インライン JSON、ADC）
• ヘルスチェックによる GCS 認証情報の検証
• 単一バケット制約モード
• 厳密な型チェックを備えた TypeScript
• 包括的なテスト（機能テスト、統合テスト、手動テスト）

機能

ツール

ツール	グループ	説明
list_buckets	readonly	Google Cloud プロジェクト内のすべての GCS バケットを一覧表示します
list_objects	readonly	プレフィックスとページネーションを指定して、バケット内のオブジェクトを一覧表示します
get_object	readonly	オブジェクトの内容をテキストとして取得します
download_object	readonly	単一のオブジェクトをローカルファイルにダウンロードします（バイナリセーフ）
download_prefix	readonly	プレフィックス以下をローカルディレクトリに再帰的にダウンロードします（バイナリセーフ）
head_bucket	readonly	バケットが存在し、アクセス可能か確認します
put_object	readwrite	インラインの文字列コンテンツからオブジェクトをアップロードまたは更新します
put_object_from_path	readwrite	ディスクからストリーミングして、単一のローカルファイルをアップロードします（バイナリセーフ、コンテキスト不要）
upload_prefix	readwrite	ディスク上のローカルディレクトリツリーを再帰的にアップロードします（バイナリセーフ、コンテキスト不要）
copy_object	readwrite	バケット内またはバケット間でオブジェクトをコピーします
create_bucket	readwrite	新しい GCS バケットを作成します
delete_object	delete	バケットからオブジェクトを削除します
delete_bucket	delete	空の GCS バケットを削除します

ローカルディスクへのダウンロード

get_object はオブジェクトの内容を UTF-8 テキストとしてインラインで返します。バイナリデータでは情報が失われ、大きなファイルや複数のファイルを一度に扱う用途には適していません。ローカルでデータを加工する場合は、代わりにダウンロードツールを使用してください。どちらのツールも 生のバイト列 をディスクにストリーミングし、readonly ツールグループに属します。

• download_object — 単一のオブジェクトをローカルファイルパスにダウンロードします。既定では、OS の一時ディレクトリ内に一意のファイルを作成します。

• download_prefix — プレフィックス以下にあるすべてのオブジェクトをローカルディレクトリに再帰的にダウンロードし、キーのパス構造をサブディレクトリとして保持します。ページネーションを使用して一覧全体を取得し、ディレクトリプレースホルダーオブジェクト（/ で終わるキー）をスキップします。バッチを中断せずにオブジェクトごとのエラーを収集し、次のマニフェストを返します。

  {
    "destinationDir": "/tmp/gcs-download-my-bucket-1700000000000",
    "objectCount": 1234,
    "totalBytes": 5678901,
    "files": [
      { "key": "logs/2024/01/data.json", "localPath": "/tmp/.../01/data.json", "size": 1234 }
    ],
    "filesTruncated": true,
    "errors": []
  }
  

  インラインの files リストには上限があります（maxInlineEntries の既定値は 100）が、objectCount と totalBytes は常にダウンロード全体の値を反映します。destinationDir を省略した場合は、OS の一時ディレクトリ内に一意のフォルダーが既定で作成されます。

ローカルディスクからのアップロード

put_object はオブジェクトの内容を文字列引数としてインラインで受け取るため、すべてのバイトがモデルコンテキストを経由し、バイナリデータには base64 が必要です。そのため、大きなファイルや大量のファイルをアップロードするには実用的ではありません。コンテキストを消費せずにファイルやフォルダーをアップロードするには、代わりにローカルパスのアップロードツールを使用してください。どちらのツールもディスクから GCS サーバーへ生のバイト列を直接ストリーミングし、メタデータのみを返します。これらは readwrite ツールグループに属するため、読み取り専用のデプロイメントで利用可能になることはありません。

• put_object_from_path — ファイルシステムのパスから単一のローカルファイルをストリーミングしてアップロードします。コンテンツタイプはファイル拡張子から自動検出されます（contentType で上書きできます）。バイナリファイル（画像、アーカイブ）は base64 なしで使用できます。{ bucket, key, sourcePath, size, etag, generation } を返します。

• upload_prefix — ローカルディレクトリ以下のすべてのファイルを再帰的にアップロードし、宛先プレフィックス以下のキーのパスとしてディレクトリ構造を保持します。ファイルへのシンボリックリンクはたどってアップロードし（ディレクトリへのリンクは循環を避けるためスキップします）、ファイルごとの失敗を収集してバッチを中断せず、マニフェストを返します。

  {
    "bucket": "my-bucket",
    "sourceDir": "/tmp/exports",
    "destPrefix": "uploads/",
    "objectCount": 1234,
    "totalBytes": 5678901,
    "files": [
      { "localPath": "/tmp/exports/01/data.json", "key": "uploads/01/data.json", "size": 1234 }
    ],
    "filesTruncated": true,
    "errors": []
  }
  

インラインの files リストには上限があります（maxInlineEntries のデフォルトは 100）が、objectCount と totalBytes は常にアップロード全体の値を反映します。destPrefix を省略すると、ファイルはバケットのルートにアップロードされます。

リソース

リソース	説明
gcs://config	サーバーの設定とステータス（デバッグ用）

ツールグループ

GCS_ENABLED_TOOLGROUPS 環境変数を使用して、利用可能なツールを制御します。

グループ	説明
readonly	読み取り専用の操作（list、get、head）
readwrite	非破壊的な書き込み操作（put、copy、create）
delete	削除操作（delete_object、delete_bucket）

例：

• GCS_ENABLED_TOOLGROUPS="readonly" - 読み取り操作のみ
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite" - 読み取りと書き込み。削除は不可
• GCS_ENABLED_TOOLGROUPS="readonly,readwrite,delete" - すべての操作
• 未設定 - すべてのツールを有効化（デフォルト）

個別ツールの制御

特定のツールを細かく制御できます。

• GCS_ENABLED_TOOLS="list_buckets,get_object" - これらのツールのみを有効化
• GCS_DISABLED_TOOLS="delete_bucket,delete_object" - これらのツールを無効化

単一バケットモード

GCS_BUCKET を使用して、すべての操作を特定のバケットに制限できます。

GCS_BUCKET="my-bucket"

設定すると：

• すべてのオブジェクト操作が自動的にこのバケットに限定されます
• バケットレベルのツール（list_buckets、create_bucket、delete_bucket、head_bucket）は非表示になります
• bucket パラメーターが自動的に挿入され、ツールの入力から非表示になります
• copy_object では、コピー元とコピー先の両方が指定されたバケットに制限されます

これにより、プロジェクトレベルのバケット一覧表示権限を付与せずに、1 つのバケットへのオブジェクトレベルのアクセスのみを持つ、最小権限のサービスアカウントを付与できます。起動時のヘルスチェックもこの制約に従います。GCS_BUCKET が設定されている場合は、そのバケットに対するオブジェクトスコープのプローブ（storage.objects.list）で認証情報を検証し、プロジェクトレベルのバケット一覧取得やバケットメタデータのプローブは呼び出しません。モードごとの正確な権限については、必要な IAM 権限を参照してください。

必要な IAM 権限

最小限必要な IAM 権限は、サーバーが単一のバケット（GCS_BUCKET）に制限されているかどうか、および有効にするツールグループによって異なります。起動時のヘルスチェックはこの制約の範囲内で認証情報を検証し、使用するモードについて下の表に記載された権限を超える権限は必要ありません。

起動時ヘルスチェック

モード	ヘルスチェックに必要な権限	備考
単一バケット（GCS_BUCKET を設定）	制約されたバケットに対する storage.objects.list	maxResults: 1 を指定して list_objects を実行します。プロジェクトレベルの storage.buckets.list やバケットメタデータの storage.buckets.get は不要なので、最小権限が適切に設定されたオブジェクト専用のサービスアカウントでも起動できます。
制約なし（GCS_BUCKET なし）	プロジェクトレベルの storage.buckets.list	プロジェクト内のバケット一覧を取得して検証します。

SKIP_HEALTH_CHECKS=true を設定すると、起動時の検証を完全に省略できます（認証情報のチェックがすべて無効になります。推奨されません）。

ツールごとの権限

ヘルスチェックに加え、各ツールには実行時に対応する GCS 権限が必要です。有効にするツールグループで必要な権限だけを付与してください。

ツール／グループ	権限
list_objects（読み取り専用）	storage.objects.list
get_object、download_object（読み取り専用）	storage.objects.get
download_prefix（読み取り専用）	storage.objects.list、storage.objects.get
list_buckets（読み取り専用）	storage.buckets.list
head_bucket（読み取り専用）	storage.buckets.get
put_object、put_object_from_path、upload_prefix、copy_object（読み書き）	storage.objects.create、storage.objects.get（これらのツールは書き込み後に各オブジェクトのメタデータを読み取り、etag／generationを返します。copy_objectはコピー元も読み取ります）
create_bucket（読み書き）	storage.buckets.create
delete_object（削除）	storage.objects.delete
delete_bucket（削除）	storage.buckets.delete

読み取り専用の単一バケット用サービスアカウントでは、バケットに対するroles/storage.objectViewerロール（またはstorage.objects.listとstorage.objects.getを含むカスタムロール）で十分です。プロジェクトレベルの権限やバケットメタデータの権限は必要ありません。

クイックスタート

設定

環境変数

変数	必須	説明	デフォルト
GCS_PROJECT_ID	はい	Google Cloud プロジェクト ID	-
GCS_SERVICE_ACCOUNT_KEY_FILE	いいえ	サービスアカウントキー JSON ファイルのパス	-
GCS_SERVICE_ACCOUNT_KEY_JSON	いいえ	サービスアカウントキー JSON の内容（直接指定）	-
GCS_BUCKET	いいえ	操作対象を単一のバケットに限定	-
GCS_ENABLED_TOOLGROUPS	いいえ	カンマ区切りのツールグループ	すべて有効
GCS_ENABLED_TOOLS	いいえ	有効にする特定のツール	-
GCS_DISABLED_TOOLS	いいえ	無効にする特定のツール	-
SKIP_HEALTH_CHECKS	いいえ	認証情報の検証をスキップ	false

認証

このサーバーは、次の3つの認証方法を優先順位順にサポートしています。

1. サービスアカウントキーファイル：GCS_SERVICE_ACCOUNT_KEY_FILE に JSON キーファイルのパスを設定します
2. サービスアカウントキーの直接指定：GCS_SERVICE_ACCOUNT_KEY_JSON に JSON の内容を直接設定します
3. アプリケーションのデフォルト認証情報（ADC）：追加の環境変数は不要です。gcloud auth application-default login を使用します

Claude Desktop の設定

MCP サーバーを初めて使用する場合は、Claude Desktop アプリケーションを用意し、公式の MCP セットアップ手順に従ってください。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gcs": {
      "command": "npx",
      "args": ["-y", "gcs-google-mcp-server"],
      "env": {
        "GCS_PROJECT_ID": "your-project-id",
        "GCS_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json",
        "GCS_ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

Claude Desktop を再起動すれば、使用を開始できます。

読み取り専用モード

より安全に確認するには、読み取り操作のみを有効にします。

{
  "env": {
    "GCS_ENABLED_TOOLGROUPS": "readonly"
  }
}

アプリケーションのデフォルト認証情報を使用する

gcloud CLI をローカルで設定済みの場合：

gcloud auth application-default login

次に、キーファイルを使わずに設定します。

{
  "env": {
    "GCS_PROJECT_ID": "your-project-id"
  }
}

開発

依存関係のインストール

npm run install-all

ビルド

npm run build

開発モードでの実行

npm run dev

テスト

# Run functional tests
npm run test:run

# Run integration tests (full MCP protocol)
npm run test:integration

# Run manual tests (real GCS - requires .env)
npm run test:manual:setup  # First time only
npm run test:manual

# Run all automated tests
npm run test:all

手動テストのセットアップ

gcs ディレクトリに .env ファイルを作成します。

GCS_PROJECT_ID=your-project-id
GCS_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account-key.json

次に実行します。

npm run test:manual

プロジェクト構成

gcs/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point with env validation
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory with DI
│   │   ├── tools.ts      # Tool registration with grouping
│   │   ├── tools/        # Individual tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   ├── gcs-client/   # Google Cloud Storage client wrapper
│   │   └── logging.ts
│   └── package.json
├── tests/                # Test suite
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/           # Mock implementations
└── package.json         # Root workspace config

ライセンス

MIT