【図解】Claude Code・CodexからGoogle Workspace/Cloud APIを直接呼ぶ方法｜OAuth 2.0とMCPの違い

「Google CloudでOAuthクライアントを作ったのに、なぜClaude CodeからDriveが読めない？」「Chromeで許可した後、token.jsonは誰が作る？」という疑問は、AIツール、実行するプログラム、Googleの認可画面、Google APIを別の役割として見ると整理できます。MCPサーバーは必須ではありません。この記事では、まず自分のPCでPythonを動かす最も単純な構成を説明します。画面や構成は2026年10月8日時点の公式資料を確認しました。

まず全体像：AIが実行するプログラムからAPIを直接呼ぶ

たとえば「来週のGoogleカレンダーの予定を読んで」とClaude CodeやCodexに頼むとします。AIツールはローカルのcalendar_read.pyを実行し、そのPythonプログラムがGoogle Calendar APIを呼びます。最初にGoogleアカウントの許可が必要なときだけ、プログラムがブラウザ認可を開始します。この流れにMCPサーバーは登場しません。

ユーザー → Claude Code / Codex → ローカルPython → Google Calendar API
                           ↘ 初回だけ既定ブラウザでGoogleに同意

Chromeに画面が出るのは、ChromeがOSの既定ブラウザになっている場合です。SafariやBraveが既定なら、そちらで開く実装が一般的です。プログラムの設定によっては、ブラウザを自動で開かず認可URLを表示することもあります。Googleのデスクトップアプリ向けOAuth説明でも、システムブラウザとローカルの戻り先を使う流れが示されています。

「認証」と「認可」、OAuthクライアントとトークンを分ける

認証は「いま操作している人は誰か」を確認することです。Googleアカウントを選び、必要ならパスキーや2段階認証で本人確認します。認可は「この連携アプリに何をさせてよいか」を決めることです。「カレンダー予定の閲覧を許可する」のは認可です。OAuth 2.0は主にAPIへのアクセス権を委任する仕組みで、ログインした人をアプリ側で識別したい場合はOpenID Connectも関わります。

「Google Cloudでトークンを発行してAIへ持たせる」と考えると混乱しやすいところです。通常のユーザー認可では、Cloud Consoleで準備するのはクライアント設定で、ユーザー固有のトークンは本人の同意の後にプログラムが受け取ります。デスクトップアプリの安全性を高めるために、認可コードを盗まれても交換しにくくするPKCE（ピクシー）と、戻ってきた要求が自分の開始したものか確かめるstateに対応する実装を選びます。詳細はGoogle公式の認可コードフローにあります。

Chromeの同意画面と、プログラム内のトークン交換を図解

ここからの図と手順は、Workspace APIをDesktop app用OAuthクライアントで呼ぶ例です。Google Cloud APIをADCで呼ぶ別ルートは、後の実践例で分けて説明します。

Google Cloud Consoleで設定する順番と、クライアント種別の選び方

Google Cloudのプロジェクトは、Workspace APIを使う場合にもOAuthアプリ設定の置き場所になります。まず「PythonなどのプログラムからAPIを直接呼ぶか、MCPを介するか」を決め、次に「自分のPCで動かすか、Webサーバーで動かすか」を決めます。OAuthクライアントの種類とブラウザから戻る先は、主にプログラムの動作場所で変わります。

Desktop appのループバック方式とWeb applicationの固定リダイレクトURIを混同すると、redirect_uri_mismatchの原因になります。とくに他サービス向けのコールバックURLを、自分のローカルプログラムへ流用しないでください。Cloud Consoleのクリック順とcredentials.json取得までは、当サイトのClaude Code・CodexからGoogle Workspaceを操作するセットアップ手順も参考になります。credentials.jsonはアプリの設定ファイル、token.jsonは本人の認可後にプログラムが保存するトークンです。

参照：Google Auth Platformの初期設定、Desktop appのOAuth、WebサーバーのOAuth。

MCPなしで試す：PythonからGoogle APIを直接呼ぶ

最初の動作確認には、カレンダーの予定を読むだけのプログラムが適しています。以下はGoogleのCalendar API Pythonクイックスタートに沿った、macOS・Linux向けの最小例です。Claude CodeやCodexのMCP設定は不要で、Pythonを実行できれば進められます。Google公式例と同様、テスト用にトークンをファイル保存する構成です。

Workspace API：初回だけブラウザで許可し、予定を取得

1. Google CloudでGoogle Calendar APIを有効化し、前節の同意画面とDesktop appのOAuthクライアントを作る。JSONをダウンロードする。
2. 作業用ディレクトリを用意し、ダウンロードしたJSONをcredentials.jsonという名前で置く。以下のコマンドはPython 3.10.7以上を想定する。
3. 必要なライブラリをインストールし、次のcalendar_read.pyを保存する。

mkdir -p ~/google-calendar-demo
cd ~/google-calendar-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Windowsなら仮想環境の作成・有効化コマンドが異なります。OAuthの仕組みは同じで、Google公式クイックスタートのPython要件を確認してください。

# calendar_read.py — Google Calendar APIを直接呼ぶ例
from datetime import datetime, timezone
from pathlib import Path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/calendar.events.readonly"]
CLIENT = Path("credentials.json")
TOKEN = Path("token.json")

creds = Credentials.from_authorized_user_file(str(TOKEN), SCOPES) if TOKEN.exists() else None
if not creds or not creds.valid:
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow = InstalledAppFlow.from_client_secrets_file(str(CLIENT), SCOPES)
        creds = flow.run_local_server(port=0)
    TOKEN.write_text(creds.to_json(), encoding="utf-8")
    TOKEN.chmod(0o600)  # macOS・Linuxで所有者だけ読めるようにする

calendar = build("calendar", "v3", credentials=creds)
events = calendar.events().list(
    calendarId="primary",
    timeMin=datetime.now(timezone.utc).isoformat(),
    maxResults=10,
    singleEvents=True,
    orderBy="startTime",
).execute().get("items", [])

for event in events:
    start = event["start"].get("dateTime", event["start"].get("date"))
    print(start, event.get("summary", "(無題)"))

同じディレクトリでpython calendar_read.pyを実行します。初回はPythonのrun_local_server(port=0)が一時的なlocalhostの待ち受け口を作り、既定ブラウザを開きます。本人が許可するとPythonがトークンを受け取り、token.jsonへ保存して予定を表示します。次回は保存済み認証情報を使い、必要なら更新します。スコープを変えた場合はGoogle公式クイックスタートに従って認可をやり直します。

最初のブラウザ同意は自分のターミナルで済ませ、その後Claude CodeやCodexに「python calendar_read.pyを実行し、表示された予定を要約して。credentials.jsonとtoken.jsonの中身は表示しないで」と頼めます。AIツールが動く場所とPythonが動く場所は同じローカルPCである必要があります。クラウド上やコンテナ内で実行すると、127.0.0.1が自分のMacを指さず、ブラウザの戻り先が届かない場合があります。実行環境のネットワーク許可も必要です。

Google Cloud API：プログラム用ADCで直接呼ぶ

Cloud StorageなどGoogle CloudのAPIだけを使うなら、ローカル開発ではApplication Default Credentials（ADC）が別の入り口になります。Google Cloud CLIをインストールし、gcloud auth application-default loginでプログラム用の認証情報を用意します。Cloudクライアントライブラリがそれを自動検出するため、通常は先ほどのDesktop app用credentials.jsonを自作する必要がありません。ただし対象APIの有効化と、操作対象へのIAM権限は必要です。

# ターミナルで実行。Pythonの仮想環境が有効な例
gcloud auth application-default login
python -m pip install google-cloud-storage

次はstorage_read.pyという別ファイルに保存するPythonコードです。YOUR_PROJECT_IDを自分のプロジェクトIDへ置き換え、ターミナルでpython storage_read.pyを実行します。

from google.cloud import storage

client = storage.Client(project="YOUR_PROJECT_ID")
for bucket in client.list_buckets():
    print(bucket.name)

このコードは認証経路を示す例です。バケット一覧を読むIAM権限がない場合は403になり、APIや課金プロジェクトの設定が必要な環境もあります。gcloud auth loginはgcloud CLI自身のログインで、プログラム用ADCとは別です。Google CloudのローカルADC設定とクライアントライブラリ認証を参照してください。

Workspaceの「スコープ」とCloudの「IAM」は別の判定

スコープは「アプリに許可を求める上限」です。スコープを付けたら全データを読めるわけではありません。本人がもともと閲覧できないファイルは通常読めず、組織の管理ポリシーも適用されます。Google CloudのプロジェクトやStorageバケットなどを操作するときは、さらに対象リソースへのIAMロールが必要です。OAuthの広いスコープだけでCloudの管理者になれるわけではありません。

前節のPython例では、SCOPESをcalendar.events.readonlyに限定しています。プログラムでもMCPでも、読み取りだけが目的なら書き込みスコープを要求しないことが基本です。

drive.fileを指定しても、何も選択していない既存のDriveファイルをすべて検索できるとは限りません。ファイル選択やアプリから開く導線が必要です。各スコープの意味はCalendar、Drive、Gmailの公式一覧で最終確認してください。

MCPを使う場合は何が変わる？

ここまでのPython直接実行ではAIツール → Python → Google APIでした。MCPを使う構成ではAIツール → MCPサーバー → Google APIになります。Googleへの同意とAPI呼び出しを担当するのがPythonスクリプトからMCPサーバーへ変わるだけで、OAuthクライアント、スコープ、トークンの基本的な役割は共通です。直接API方式を使うだけなら、以下のMCP登録コマンドは不要です。

自分のPCで動かすローカルMCP

ローカルMCPでは、AIツールがPC上のMCPプロセスを起動し、そのMCPがGoogleへOAuth認可を求めます。CLIの登録の形は次のとおりです。<MCPの起動コマンド>は選んだ連携プログラムの説明にある実際のコマンドに置き換えます。MCPによって認証開始方法やトークン保存先が違うため、この行だけではGoogle接続は完了しません。

# Claude Code（ローカルのstdio MCP）
claude mcp add --transport stdio google-local -- <MCPの起動コマンド>

# Codex（ローカルのstdio MCP）
codex mcp add google-local -- <MCPの起動コマンド>

この構成で見ているGoogleの同意画面は、ローカルMCP → Googleの認可です。MCPが備える初回ログイン手順に従います。Claude CodeのMCPドキュメントとOpenAI DocsのCodex MCPガイドは登録形式を説明しています。

独自のリモートMCPを作る場合

WebサーバーにMCPを置くと、認可の境界が二つになり得ます。①Claude Code/CodexがそのMCPサーバーを利用してよいかと、②MCPサーバーがユーザーのGoogleデータへアクセスしてよいかです。前者のclaude mcp login <名前>やcodex mcp login <名前>は、対応するリモートMCPへのログインです。これだけでGoogle側のOAuth同意が完了するとは限りません。独自サーバーはGoogle用のWeb applicationクライアント、Googleのコールバック、ユーザー別トークン保管も設計します。

Google公式のリモートMCPを使う場合

Google自身が運営するWorkspace用MCPも公開されています。ただし2026年10月時点の公式案内ではDeveloper Preview Programへの参加が前提です。自前のバックエンドでGoogleトークンを保管する構成とは異なり、設定も製品ごとに分かれます。誰でも同じ手順で今すぐ利用できる選択肢として扱わず、Googleの参加条件と対応製品を先に確認してください。

Google CloudにはCloudサービス別の公式リモートMCPもあります。こちらはWorkspace用とは設定体系が別です。Google Cloudの公式MCPを呼ぶ人にはroles/mcp.toolUserに加え、実際に操作するサービスのIAMロールが必要です。Google CloudのMCP権限ガイドで対象サービスを確認してください。Cloud CLIのリモートMCPはPreviewとして案内されています。

よくある詰まり方と、安全に使い続けるための確認

GoogleのAudienceの説明によると、ExternalのTestingは最大100人のテストユーザーに限定され、名前・メール・プロフィールのみの例外を除いて認可は7日で切れます。個人用の試作でも「トークンが壊れた」と早合点せず、この設定を見ます。外部向けに公開し、機微・制限付きスコープを使う場合には検証要件も確認してください。

最初の一歩は、「予定を読む」など一つの読み取り操作を決める → そのAPIとスコープを調べる → Desktop appクライアントとPythonを用意する → 自分で初回の同意を行う → AIツールからPythonを実行して結果を読む、という順番です。MCPが必要になった段階で接続方式を追加すれば十分です。実際のCloud Consoleのクリック手順は既存のセットアップ記事も参照できます。

参考資料：Calendar API Pythonクイックスタート、Google OAuth 2.0 for Desktop Apps、Google OAuth 2.0 for Web Server Applications、Google Workspaceの認証・認可、Google Cloud ADC、Claude Code MCP、OpenAI Docs Codex MCP。画面の名称と提供状況は2026年10月8日に確認。