Claude Code + Gmail API でメール自動化｜スコープを1段ずつ広げる手順

Claude Code に頼めば、Gmail API を使って、メールにラベルを付ける、添付の PDF を保存する、決まった文面で返信する、といった Python のスクリプトを書いてもらえます。手間がかかるのはその手前です。Google Cloud で Gmail API を有効にし、OAuth の同意画面とクライアントを作り、credentials.json をスクリプトと同じフォルダに置きます。ここまでは Google のクイックスタートどおりに進めます。そのうえで決めておくことが1つあります。書かせたスクリプトに、どこまでの権限（スコープ）を渡し、どこで動かすかです。

当社は Claude Code の導入と、Google Workspace の運用を支援する側の会社です。この記事は、個人の Gmail か Google Workspace のアカウントで自分のメールボックスを自動で整理したい人と、それを許可する管理者に向けて書いています。組織の全員分のメールをサーバーで処理する方法、Apps Script、Gmail のアドオンは扱いません。仕様と上限は、2026年10月13日に Google と Anthropic の公式ページで確かめたものです。

コードを書かない人の始め方と、任せていい仕事の線引きを、動画にまとめています↓↓

作例：件名に「請求書」とある PDF にラベルを付けて保存する

この記事では、例を1つに決めて最後まで使います。件名に「請求書」を含み、PDF が添付されたメールに「請求書」のラベルを付け、PDF をパソコンのフォルダに日付つきで保存するスクリプトです。これは説明のための作例で、特定の会社の運用ではありません。

先に、スクリプトが本当に要るかを確かめます。Gmail のフィルタは、検索の条件に合う受信メールに、ラベルを付ける、アーカイブする、削除する、スターを付ける、自動で転送する、をスクリプトなしでできます。後から届いた返信には、検索の条件に合うものにだけフィルタがかかります（Gmail ヘルプ「メールのフィルタルールの作成」）。作例のうちラベルを付けるだけならフィルタで足ります。PDF をパソコンのフォルダに保存するところが、API のスクリプトが要る部分です。ラベルとフィルタが返信にどう効くかは、Gmail のスレッド表示の記事に書いています。

この記事に関連するサービス

Claude 導入支援Claudeを、会社の決まりの中で使える状態まで。詳しく見る →AI活用支援生成AIを、業務に組み込むところまで詳しく見る →ChatGPT 導入支援ChatGPTを、会社の決まりの中で使える状態まで。詳しく見る →AIセキュリティ診断・規約・ルール整備AIを使う前に、出す前に。安全の確認と、規約・ルールの整備を詳しく見る →Microsoft 365 導入支援Exchange・SharePoint・Teamsの移行から権限設計・Copilot活用まで詳しく見る →

Google Cloud の準備は、クイックスタートの順に5つ

Google の Python クイックスタートの順に進めます。Python は 3.10.7 以上が要ります。画面の名前は2026年10月13日時点の日本語の表示で、同意画面とクライアントは［Google Auth Platform］の下にあります。個人の Gmail では［対象］に外部を選ぶことになるので、［対象］→［テストユーザー］→［ユーザーを追加］で自分のアドレスを足しておきます。テスト中の同意画面で同意できるのは、ここに登録したテストユーザー（100人まで）だけです（Google Cloud ヘルプ「Manage App Audience」）。

クイックスタートにある、ライブラリを入れるコマンド（python3 で動かない環境では python に替える）

python3 -m pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

credentials.json と token.json は、どちらも外に出してはいけないファイルです。token.json には、利用者のアクセストークンとリフレッシュトークンが入ります（クイックスタートのコードの注記）。Git で管理するフォルダなら .gitignore に入れ、チャットに中身を貼りません。スクリプトのスコープを変えたら、token.json を消して同意し直すよう、クイックスタートのコードに書かれています。

同意画面の「対象」で、認可の期限が変わる

手順2の Audience（対象）の選び方で、スクリプトが何日動き続けるかが変わります。いちばん止まりやすいのは、個人の Gmail で作ったときです。

出典は、Google Cloud ヘルプの「Manage App Audience」、OAuth 2.0 の「Refresh token expiration」、「Unverified apps」です。OAuth 2.0 のページは、外部・テスト中のリフレッシュトークンを「7日で期限が切れる」と書いています（名前・メール・プロフィールだけを求めるアプリは除く）。Gmail のスコープは名前・メールだけではないので、作例はこの7日に当たります。同じページは、トークンが使えなくなるほかの場合として、6か月使われなかったとき、Gmail のスコープを含むトークンで利用者がパスワードを変えたとき、管理者がそのサービスを制限したとき、を挙げています。

本番にすれば7日の期限は無くなりますが、今度は Google の確認が話に入ります。Google は、確認が要らない場合を3つ挙げています。1つは自分用のアプリで、利用者が100人未満のものです。ログインのときに「未確認のアプリ」の警告を進めて使います。ほかの2つは、Google Workspace などの組織の中だけで使う内部のアプリと、開発・テスト中のアプリです（Google Cloud ヘルプ「When is verification not needed」）。作例のように、自分のパソコンで自分のメールボックスだけを扱うなら自分用に当たります。100人を超えて配るなら、制限付きのスコープの確認を受け、その最後の段階のセキュリティ評価（CASA）も受けます。評価は毎年やり直しです（Google Cloud ヘルプ「Security Assessment」）。社内に配るなら、Workspace の内部（Internal）で作れば、この確認の対象から外れます。

Google Workspace では、管理者の設定で止まることがある

会社の Google Workspace のアカウントで動かすなら、先に管理者と話します。管理者は管理コンソールの［セキュリティ］→［アクセスとデータ管理］→［API の制御］で、アプリごとに「信頼できる」「限定」「特定の Google データ」「ブロック」を決められます。Gmail のサービスを「制限付き」にすると、信頼されていないアプリは動かなくなり、トークンも取り消されます。Gmail では、リスクの高い OAuth スコープへの接続を細かく制限できます。その一覧には gmail.send だけでなく、作例の1段目の gmail.readonly と2段目の gmail.modify も入っています。組織で作った内部のアプリに制限付きの API を使わせるための、「内部アプリを信頼する」というチェックボックスもあります（Google Workspace 管理者ヘルプ）。管理者の設定で止められたとき、リフレッシュトークンの更新は admin_policy_enforced というエラーで失敗します（Google for Developers「Using OAuth 2.0」）。

組織の全員分のメールを、利用者の同意なしにサーバーで処理する「ドメイン全体の委任」もあります。ただし、設定には特権管理者の権限が要り、委任したアプリはすべての利用者のデータにアクセスできるようになります（Google Workspace 管理者ヘルプ）。自分のメールボックスを整理する作例の範囲を超えるので、この記事では扱いません。

スコープは「読むだけ」から段で上げる

スクリプトが Gmail でどこまでできるかの上限は、コードではなく、同意したスコープで決まります。Google は「できるだけ狭いスコープを選ぶ」よう書いています。Gmail のおもなスコープと、Google の説明、区分は次のとおりです（Google for Developers「Choose Gmail API scopes」）。

作例で書き込みに要るのは gmail.modify です。メールにまとめてラベルを付ける batchModify は、gmail.modify か、それより広いスコープでしか呼べないからです（メソッドの参照）。ところが gmail.modify には、メールの送信も含まれます。スコープで送信を外すことはできないので、作例の2段目のスクリプトに送信のコードが入っていないことは、Claude Code に書かせた後に人がコードを読んで確かめます。messages().send や drafts().send の呼び出しが無いかを見ます。

1段目は gmail.readonly で動かし、対象の件数だけを見ます。読むだけのスコープなら、条件の書き間違いがあっても、メールボックスは何も変わりません。件数が思ったとおりなら、2段目で gmail.modify に上げます。作例では、スコープごとに token のファイルを分けて、読むだけの token では書き込めないようにしています。送信の段は、ラベル付けとは別のスクリプトにして gmail.send を使います。

Claude Code への頼み方：条件は Gmail の検索の式で渡す

どのメールを対象にするかは、Gmail の検索窓に入れる式でそのまま渡すと、書かれたコードの条件を自分で確かめやすくなります。作例の条件は subject:請求書 has:attachment filename:pdf -label:請求書 です。subject: は件名、has:attachment は添付あり、filename:pdf は PDF の添付、先頭の – は除外で、すでに「請求書」のラベルが付いたものを外します（Gmail ヘルプ「Gmail の検索を絞り込む」）。式はまず Gmail の検索窓に入れて、出てくるメールを目で見ておきます。

作例：Claude Code への指示

作業フォルダの credentials.json を使って、Gmail API の Python のスクリプトを書いてください。
対象は、Gmail の検索の式 subject:請求書 has:attachment filename:pdf -label:請求書 に合うメールです。
・引数なしで動かしたときは、スコープ gmail.readonly で対象の件数だけを表示し、何も変えない
・--apply を付けたときだけ、スコープ gmail.modify で「請求書」ラベルを付け、PDF を attachments フォルダに「日付_メールのID_ファイル名」で保存する
・スコープごとに token のファイルを分ける
・メールを送信するコードは書かない
・件名や差出人は画面に出さない

指示に入れたのは、対象（検索の式）、メールにする操作（ラベル）、出力先（フォルダとファイル名）、それにスコープと段です。最後の「件名や差出人は画面に出さない」は、スクリプトを Claude Code の中で動かしたときの話につながります。これは、コードの後の「どこで動かすか」の節で書きます。

作例のコード

次のコードは、上の指示で書かせたときの形として、この記事のために用意した作例です。Python の構文の確認だけをしたもので、Gmail に対しては動かしていません。自分のメールボックスで使う前に、1段目で件数を確かめてください。

作例：gmail_invoice.py（構文の確認だけで、Gmail に対しては動かしていない）

"""作例：件名に「請求書」を含み、PDF が付いたメールに「請求書」ラベルを付け、PDF を保存する。
  python gmail_invoice.py          読むだけ。対象の件数を表示する（何も変えない）
  python gmail_invoice.py --apply  ラベルを付け、PDF を attachments に保存する
"""
import argparse
import base64
import re
from datetime import datetime
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
QUERY = 'subject:請求書 has:attachment filename:pdf -label:請求書'
LABEL = '請求書'
SAVE_DIR = Path('attachments')
READONLY = 'https://www.googleapis.com/auth/gmail.readonly'
MODIFY = 'https://www.googleapis.com/auth/gmail.modify'
def gmail(scope, token_file):
    """スコープごとに別の token ファイルを使う（読むだけの token では書き込めない）"""
    token = Path(token_file)
    creds = Credentials.from_authorized_user_file(str(token), [scope]) 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('credentials.json', [scope])
            creds = flow.run_local_server(port=0)
        token.write_text(creds.to_json(), encoding='utf-8')
    return build('gmail', 'v1', credentials=creds)
def find_ids(svc):
    ids, page = [], None
    while True:
        res = svc.users().messages().list(userId='me', q=QUERY, maxResults=100, pageToken=page).execute()
        ids += [m['id'] for m in res.get('messages', [])]
        page = res.get('nextPageToken')
        if not page:
            return ids
def pdf_parts(part):
    """添付は入れ子の parts の中にあることがあるので、たどって探す"""
    name = part.get('filename', '')
    if name.lower().endswith('.pdf') and part.get('body', {}).get('attachmentId'):
        yield part
    for child in part.get('parts', []):
        yield from pdf_parts(child)
def label_id(svc, name):
    for lb in svc.users().labels().list(userId='me').execute().get('labels', []):
        if lb['name'] == name:
            return lb['id']
    return svc.users().labels().create(userId='me', body={'name': name}).execute()['id']
def apply(svc, ids):
    SAVE_DIR.mkdir(exist_ok=True)
    for mid in ids:
        msg = svc.users().messages().get(userId='me', id=mid, format='full').execute()
        day = datetime.fromtimestamp(int(msg['internalDate']) / 1000).strftime('%Y-%m-%d')
        for part in pdf_parts(msg['payload']):
            att = svc.users().messages().attachments().get(
                userId='me', messageId=mid, id=part['body']['attachmentId']).execute()
            safe = re.sub(r'[\\/:*?"<>|]', '_', part['filename'])
            (SAVE_DIR / f'{day}_{mid}_{safe}').write_bytes(base64.urlsafe_b64decode(att['data']))
    lid = label_id(svc, LABEL)
    for i in range(0, len(ids), 1000):  # batchModify は1回に1000件まで
        svc.users().messages().batchModify(
            userId='me', body={'ids': ids[i:i + 1000], 'addLabelIds': [lid]}).execute()
def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('--apply', action='store_true')
    args = ap.parse_args()
    if not args.apply:
        ids = find_ids(gmail(READONLY, 'token_readonly.json'))
        print(f'対象 {len(ids)} 件（何も変えていません）')
        return
    svc = gmail(MODIFY, 'token_modify.json')
    ids = find_ids(svc)
    apply(svc, ids)
    print(f'{len(ids)} 件にラベルを付け、PDF を保存しました')
if __name__ == '__main__':
    main()

コードの中で、Gmail API の決まりに合わせたところは3つあります。messages().list は1回に既定で100件、最大で500件までしか返さないので、nextPageToken をたどって全件を集めます（messages.list の参照）。batchModify は1回に1000件までなので、1000件ずつに分けます（batchModify の参照）。添付は、メールの parts の中にさらに parts が入れ子になっていることがあるので、たどって PDF を探します。

どこで動かすか：Claude Code の中で走らせない段がある

Claude Code は、書いたスクリプトをそのまま実行することもできます。ただ、Claude の作業の範囲（コンテキスト）には、ファイルの中身とコマンドの出力が入ります（Claude Code「How Claude Code works」）。スクリプトが件名や差出人を画面に出せば、それも Claude に送られる会話の一部になります。作例で「件名や差出人は画面に出さない」と指示したのはこのためです。

送られた会話が学習に使われるかは、契約で分かれます。Team・Enterprise・API の商用の契約では、顧客が提供を選んだ場合を除いて学習に使わず、保存は標準で30日です。個人向けの Free・Pro・Max は、改善に使う設定がオンなら学習に使われて5年保存、オフなら30日保存です（Claude Code「Data usage」）。オフにしていても、フィードバックとして送った分と、安全のための審査の対象になった分は学習に使われます（Anthropic の利用規約「Consumer Terms」）。取引先のメールの件名には、会社名や人の名前が入ります。Claude Code は会話の記録を、手元の ~/.claude/projects/ にも平文で既定30日残します（同じ「Data usage」）。件名を確かめる1段目は、Claude Code の外の、自分のターミナルで動かすのが確実です。

もう1つ、Claude Code のチェックポイントで元に戻せるのは、パソコンのファイルの書き換えだけです。データベースや API のような外のシステムへの操作は戻せない、と公式に書かれています（「How Claude Code works」）。–apply で付けたラベルや、送ったメールは、Claude Code では取り消せません。そこで作業フォルダの .claude/settings.json に、token を読ませない設定と、Claude Code が –apply を付けて実行しようとしたときに確認を求める設定を書いておきます。

作例：.claude/settings.json

{
  "permissions": {
    "deny": [
      "Read(./credentials.json)",
      "Read(./token_readonly.json)",
      "Read(./token_modify.json)"
    ],
    "ask": [
      "Bash(* gmail_invoice.py --apply*)",
      "PowerShell(* gmail_invoice.py --apply*)"
    ]
  }
}

ルールは deny、ask、allow の順に照らし合わされます。* の無いルールは、その文字列どおりのコマンドにしか当たりません。そこで ask では、* で python と python3 の違いや後ろの引数を吸収しています。Windows で PowerShell の道具から動かす場合に備えて、PowerShell のルールも並べています（Claude Code「Configure permissions」）。それでも別の書き方で起動すれば当たらないことがあるので、–apply は自分のターミナルで動かすのが基本です。

deny が止めるのは、Claude の道具と、cat や head のように Claude Code が見分けられるコマンドまでです。Python のスクリプトが自分で開くファイルは止めません（同じページ）。作例のスクリプトが token を読むのは、動くために要ることです。ただし同じ理由で、Claude が python のコマンドで token を開いて中身を出力すれば、deny を書いていても会話に入ります。すべてのプロセスを OS の単位で止めるのはサンドボックスで、macOS・Linux・WSL2 で動きます。Windows でそのまま動かすときは使えないので、Windows なら WSL2 の中で Claude Code を動かします（Claude Code「Configure the sandboxed Bash tool」）。deny の効く範囲は、経理で Claude Code を使うときの記事にも書いています。

毎日動かすなら、Windows ならタスク スケジューラ、Mac や Linux なら cron に、python gmail_invoice.py –apply を登録します。定期の実行は Python のスクリプトだけで動き、Claude Code も Claude も通りません。Claude を使うのは、スクリプトを書かせる・直させるときだけです。一方で、スクリプトの中から Claude の API を呼んでメールの内容で振り分けさせるなら、その分は API の利用になり、メールの本文が Anthropic に送られます。

ほかの自動化に広げるとき

作例と同じ形で、自動返信や通知にも広げられます。広げるときに変わるのは、要るスコープと、気をつける点です。

返信を相手のスレッドに入れるには、件名を合わせ、References と In-Reply-To のヘッダーを付けます（Google for Developers「Sending email」）。送るメールの本文は base64url で符号化して raw に入れます。自動返信は相手に届いてから取り消せないので、作例の1段目と同じく、まず対象の件数と宛先の数を確かめてから送る段に進みます。

上限と費用

Gmail API の使用量は「単位」で数えます。2026年5月1日以降に作ったプロジェクトでは、1人の利用者が1つのプロジェクトで使えるのは1分あたり6,000単位です（プロジェクト全体では1分あたり1,200,000単位）。2025年11月〜2026年4月にこの API を使っていたプロジェクトは、前の割り当てのままです。単位はメソッドごとに違います（Google for Developers「Usage limits」）。

単純に割ると、messages.get は1分に300回、messages.send は1分に60回で上限に届きます（検算は割り算だけ）。作例はメール1通ごとに get と attachments.get を呼ぶので、数千件を一度に処理するときは間を空けます。1つのプロジェクトで1日80,000,000単位のしきい値までなら、追加の費用はかかりません。しきい値を超えた分の請求の詳細は、2026年中に、変更の90日以上前に知らせると、同じページに書かれています。作例の規模では届きません（messages.get の20単位で割ると1日400万回で、検算は割り算だけです）。

送信には、API とは別に Gmail の上限があります。API では1通の宛先は500件までです。Google Workspace の利用者は1日2,000通まで（試用中は500通）、社外の宛先は1日3,000件までです。1日は、暦の日ではなく直近24時間で数えます。上限に達すると最長24時間送れなくなります（Google Workspace 管理者ヘルプ）。個人の Gmail は1日500通を超えると送れなくなり、1〜24時間で送れるようになります（Gmail ヘルプ）。Workspace のページは、API から送った分をこの上限に数えるかを書いていないので、自動返信の件数は上限より十分少なく抑えておきます。

Claude Code は、Pro・Max・Team・Enterprise のどのプランにも含まれます（Claude の料金のページ）。Pro・Max・Team の定額の枠の中では、スクリプトを書かせた分は請求ではなく上限の消費になります。追加の利用をオンにしていれば、枠を超えた分が請求になります。Enterprise は席の料金に、API の単価での使用量が加わります。Console の API は使った分だけ請求されます。「どこで動かすか」の節のとおり、定期の実行は Claude を通らないので、この費用は増えません。

動かないとき

出典は、Google for Developers「Using OAuth 2.0」、Google Cloud ヘルプ、Python クイックスタート、「Unverified apps」、「When is verification not needed」、送信の上限のページです。エラーの文面を Claude Code に渡せば、どこを直すかを一緒に探せます。そのときも、token の中身は貼りません。

決まった条件で回すならスクリプト、中身を読ませるならコネクタ

作例のスクリプトは、同じ検索の式で、毎回同じ操作をします。メールを1通ずつ読んで判断させたいなら、別の道もあります。Claude と Claude Desktop の Gmail コネクタは、自然な言葉でのメールの検索と読み取り、下書き、ラベルとスレッドの整理ができます。送信・返信・転送は、既定では1回ごとに利用者の承認を求めます。添付は、ファイル名などの情報は見えますが、中身は見えません。Team と Enterprise では、組織の Owner か Primary Owner がコネクタを有効にしてから各自がつなぎます（Claude ヘルプセンター）。Google も、AI から Gmail を扱うための MCP サーバーを、開発者向けの先行公開（Developer Preview）で出しています。使うには Google Workspace のデベロッパー プレビュー プログラムへの参加が要ります。スレッドの検索と取得、ラベル付け、下書きの作成ができ、送信の道具はありません（Google for Developers「Configure the Gmail MCP server」）。

作例のように PDF をパソコンのフォルダに保存する作業は、コネクタではできません（添付の中身が見えないため）。決まった条件で毎日回す作業はスクリプト、1通ずつ読んで下書きまで作る作業はコネクタ、と分けると、それぞれの権限を狭く保てます。

まず、読むだけのスコープで件数を出す

最初の1回は、Claude Code に作例のような1段目だけのスクリプトを書かせ、自分のターミナルで動かして、対象の件数を見てください。その件数が Gmail の検索窓で見た数と合ってから、–apply と、settings.json の ask の設定に進みます。

会社のアカウントで使うときの、スコープの決め方や、Claude Code に何を読ませるかの決め方は、当社のClaude Code 導入支援で一緒に進められます。

仕様と上限は2026年10月13日に、Google for Developers、Google Cloud ヘルプ、Gmail ヘルプ、Google Workspace 管理者ヘルプ、Claude Code の公式ドキュメント、Claude の料金のページで確かめました。画面の名前と上限は変わることがあります。