Claude Code×Google Workspace API（スプレッドシート・Gmail・カレンダー）【2026】GASとの使い分けも解説

python -m venv .venv && source .venv/bin/activate
pip install gspread google-api-python-client google-auth google-auth-oauthlib python-dotenv

backoffice-agent/
├── CLAUDE.md
├── .claude/settings.json      # permissions
├── .env                       # シートのキー、秘密ファイルのパス
├── secrets/                   # service_account.json / credentials.json / token.json
├── scripts/
│   ├── gauth.py               # 認証の共通処理
│   ├── read/
│   │   ├── sheet_profile.py   # シートの列ごとの傾向を出す
│   │   ├── gmail_fetch.py     # ラベルの問い合わせ → data/inquiries.json
│   │   └── calendar_hours.py  # 会議時間の集計 → data/meeting_hours.csv
│   └── write/
│       ├── sheet_clean.py     # 整形ルール → 新しいシートに出力＋グラフ
│       └── gmail_draft.py     # drafts/replies.json → Gmailの下書き
├── gas/                       # clasp で管理する GAS（後述）
├── data/                      # 取得データ（.gitignore）
└── drafts/                    # Claude が書く下書き・ルール案

"""認証の共通処理。シートはサービスアカウント、Gmail・カレンダーはOAuth（ユーザー同意）"""
import os
from pathlib import Path

import gspread
from dotenv import load_dotenv
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

load_dotenv()
SECRETS = Path(os.environ.get("SECRETS_DIR", "secrets"))
SCOPES = [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/calendar.readonly",
]


def sheets() -> gspread.Client:
    return gspread.service_account(filename=str(SECRETS / "service_account.json"))


def user_creds() -> Credentials:
    token = SECRETS / "token.json"
    creds = Credentials.from_authorized_user_file(str(token), SCOPES) if token.exists() else None
    if creds and creds.valid:
        return creds
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        # 初回だけブラウザが開き、同意すると token.json が保存される（人が手元で実行する）
        flow = InstalledAppFlow.from_client_secrets_file(str(SECRETS / "credentials.json"), SCOPES)
        creds = flow.run_local_server(port=0)
    token.write_text(creds.to_json())
    return creds


def gmail():
    return build("gmail", "v1", credentials=user_creds())


def calendar():
    return build("calendar", "v3", credentials=user_creds())

"""使い方: python scripts/read/sheet_profile.py <シート名>
列ごとに 件数・空欄数・ユニーク数・よく出る値（上位5件）を出す。全行は出さない。"""
import json
import os
import sys
from collections import Counter
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from gauth import sheets  # noqa: E402

ws = sheets().open_by_key(os.environ["SHEET_KEY"]).worksheet(sys.argv[1])
rows = ws.get_all_values()
header, body = rows[0], rows[1:]

profile = []
for i, name in enumerate(header):
    values = [r[i].strip() if i < len(r) else "" for r in body]
    filled = [v for v in values if v]
    profile.append({
        "column": name,
        "rows": len(values),
        "blank": len(values) - len(filled),
        "unique": len(set(filled)),
        "top_values": Counter(filled).most_common(5),
    })

Path("data").mkdir(exist_ok=True)
Path("data/profile.json").write_text(json.dumps(profile, ensure_ascii=False, indent=1), encoding="utf-8")
print(f"{len(header)} columns / {len(body)} rows -> data/profile.json")

{
  "source": "売上台帳",
  "date_cols": ["日付"],
  "number_cols": ["金額"],
  "replace": { "取引先": { "(株)ABC": "株式会社ABC", "ABC": "株式会社ABC" } },
  "dedupe_on": ["日付", "取引先", "金額"],
  "group_by": "取引先",
  "sum_col": "金額"
}

"""使い方: python scripts/write/sheet_clean.py drafts/clean_rules.json [--commit]
元シートは読むだけ。整形結果と集計を「整形_YYYYMMDD」「集計_YYYYMMDD」という新しいシートに書き、集計にグラフを付ける。"""
import argparse
import json
import os
import re
import sys
import unicodedata
from collections import defaultdict
from datetime import date, datetime
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from gauth import sheets  # noqa: E402

DATE_FORMATS = ("%Y/%m/%d", "%Y-%m-%d", "%Y年%m月%d日", "%Y.%m.%d")


def norm(v: str) -> str:
    # 全角英数・全角スペースを半角に（NFKC正規化）、連続する空白を1つに
    return re.sub(r"\s+", " ", unicodedata.normalize("NFKC", v)).strip()


def to_date(v: str) -> str:
    for fmt in DATE_FORMATS:
        try:
            return datetime.strptime(v, fmt).date().isoformat()
        except ValueError:
            continue
    return v  # 解釈できない値はそのまま残し、後で人が確認する


def to_number(v: str):
    s = v.replace(",", "").replace("円", "").replace("¥", "").strip()
    try:
        return float(s) if "." in s else int(s)
    except ValueError:
        return v


def clean(rows: list, rules: dict) -> list:
    header = [norm(h) for h in rows[0]]
    idx = {h: i for i, h in enumerate(header)}
    out, seen = [header], set()
    for r in rows[1:]:
        r = [norm(v) for v in r] + [""] * (len(header) - len(r))
        for col, mapping in rules.get("replace", {}).items():
            r[idx[col]] = mapping.get(r[idx[col]], r[idx[col]])
        for col in rules.get("date_cols", []):
            r[idx[col]] = to_date(r[idx[col]])
        for col in rules.get("number_cols", []):
            r[idx[col]] = to_number(r[idx[col]])
        key = tuple(r[idx[c]] for c in rules.get("dedupe_on", []))
        if key and key in seen:
            continue
        seen.add(key)
        out.append(r)
    return out


def summarize(table: list, group_by: str, sum_col: str) -> list:
    idx = {h: i for i, h in enumerate(table[0])}
    totals = defaultdict(int)
    for r in table[1:]:
        if isinstance(r[idx[sum_col]], (int, float)):
            totals[r[idx[group_by]]] += r[idx[sum_col]]
    ranked = sorted(totals.items(), key=lambda x: x[1], reverse=True)
    return [[group_by, f"{sum_col}合計"]] + [list(x) for x in ranked]


def chart_request(sheet_id: int, n_rows: int, title: str) -> dict:
    def rng(col: int) -> dict:
        return {"sourceRange": {"sources": [{"sheetId": sheet_id, "startRowIndex": 0, "endRowIndex": n_rows,
                                             "startColumnIndex": col, "endColumnIndex": col + 1}]}}
    return {"addChart": {"chart": {
        "spec": {"title": title, "basicChart": {
            "chartType": "COLUMN", "legendPosition": "NO_LEGEND", "headerCount": 1,
            "domains": [{"domain": rng(0)}],
            "series": [{"series": rng(1), "targetAxis": "LEFT_AXIS"}]}},
        "position": {"overlayPosition": {"anchorCell": {"sheetId": sheet_id, "rowIndex": 0, "columnIndex": 3}}},
    }}}


if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("rules")
    ap.add_argument("--commit", action="store_true")
    args = ap.parse_args()
    rules = json.loads(Path(args.rules).read_text(encoding="utf-8"))

    sh = sheets().open_by_key(os.environ["SHEET_KEY"])
    rows = sh.worksheet(rules["source"]).get_all_values()
    table = clean(rows, rules)
    summary = summarize(table, rules["group_by"], rules["sum_col"])
    print(f"元 {len(rows) - 1} 行 → 整形後 {len(table) - 1} 行（重複除去 {len(rows) - len(table)} 行）")
    for line in summary[:10]:
        print("  ", line)
    if not args.commit:
        print("\n(dry-run) 問題なければ --commit を付けて再実行してください")
        sys.exit(0)

    stamp = date.today().strftime("%Y%m%d")
    ws = sh.add_worksheet(title=f"整形_{stamp}", rows=len(table) + 10, cols=len(table[0]))
    ws.update(range_name="A1", values=table)
    ws.freeze(rows=1)
    ws_sum = sh.add_worksheet(title=f"集計_{stamp}", rows=len(summary) + 10, cols=3)
    ws_sum.update(range_name="A1", values=summary)
    sh.batch_update({"requests": [chart_request(ws_sum.id, len(summary), f"{rules['sum_col']}（{rules['group_by']}別）")]})
    print("written:", ws.title, ws_sum.title)

"""使い方: python scripts/read/gmail_fetch.py 問い合わせ 7
指定ラベルの直近N日のメールを data/inquiries.json に保存する（本文は先頭3000字まで）。"""
import base64
import json
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from gauth import gmail  # noqa: E402

service = gmail()


def plain_text(payload: dict) -> str:
    # マルチパートを再帰的にたどり、text/plain の本文を取り出す
    if payload.get("mimeType") == "text/plain" and payload.get("body", {}).get("data"):
        return base64.urlsafe_b64decode(payload["body"]["data"]).decode("utf-8", errors="replace")
    for part in payload.get("parts", []):
        text = plain_text(part)
        if text:
            return text
    return ""


label, days = sys.argv[1], int(sys.argv[2]) if len(sys.argv) > 2 else 7
resp = service.users().messages().list(userId="me", q=f"label:{label} newer_than:{days}d", maxResults=50).execute()
items = []
for ref in resp.get("messages", []):
    msg = service.users().messages().get(userId="me", id=ref["id"], format="full").execute()
    headers = {h["name"].lower(): h["value"] for h in msg["payload"]["headers"]}
    items.append({
        "id": msg["id"],
        "thread_id": msg["threadId"],
        "message_id": headers.get("message-id", ""),
        "from": headers.get("from", ""),
        "subject": headers.get("subject", ""),
        "date": headers.get("date", ""),
        "body": plain_text(msg["payload"])[:3000],
    })

Path("data").mkdir(exist_ok=True)
Path("data/inquiries.json").write_text(json.dumps(items, ensure_ascii=False, indent=1), encoding="utf-8")
print(f"{len(items)} messages -> data/inquiries.json")

"""使い方: python scripts/write/gmail_draft.py drafts/replies.json [--commit]
replies.json の形式: [{"id": "元メールのID", "category": "見積依頼", "body": "返信本文"}]
宛先・件名・スレッドは data/inquiries.json の元メールから引く。このスクリプトは下書きを作るだけで、送信はしない。"""
import argparse
import base64
import json
import sys
from email.message import EmailMessage
from email.utils import parseaddr
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from gauth import gmail  # noqa: E402

MAX_DRAFTS = 20

if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("replies")
    ap.add_argument("--commit", action="store_true")
    args = ap.parse_args()

    originals = {m["id"]: m for m in json.loads(Path("data/inquiries.json").read_text(encoding="utf-8"))}
    replies = json.loads(Path(args.replies).read_text(encoding="utf-8"))
    if len(replies) > MAX_DRAFTS:
        sys.exit(f"{len(replies)}件は多すぎます（上限{MAX_DRAFTS}件）")

    messages = []
    for r in replies:
        orig = originals.get(r["id"])
        if orig is None:
            sys.exit(f"元メールが見つかりません: {r['id']}")  # 存在しないIDへの返信は作らない
        msg = EmailMessage()
        msg["To"] = parseaddr(orig["from"])[1]
        subject = orig["subject"]
        msg["Subject"] = subject if subject.lower().startswith("re:") else f"Re: {subject}"
        msg["In-Reply-To"] = orig["message_id"]
        msg["References"] = orig["message_id"]
        msg.set_content(r["body"])
        messages.append((orig, msg))
        print(f"[{r['category']}] To: {msg['To']} / {msg['Subject']}\n{r['body'][:200]}\n")

    if not args.commit:
        print("(dry-run) 問題なければ --commit を付けて再実行してください（作られるのは下書きのみ）")
        sys.exit(0)
    service = gmail()
    for orig, msg in messages:
        raw = base64.urlsafe_b64encode(msg.as_bytes()).decode()
        service.users().drafts().create(
            userId="me", body={"message": {"raw": raw, "threadId": orig["thread_id"]}}
        ).execute()
    print(f"{len(messages)} drafts created（送信はGmailで人が行ってください）")

"""使い方: python scripts/read/calendar_hours.py 2026-09-01 2026-10-01
期間内の予定を分類し、週×分類ごとの会議時間を data/meeting_hours.csv に出す。"""
import csv
import sys
from collections import defaultdict
from datetime import datetime, timedelta, timezone
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from gauth import calendar  # noqa: E402

JST = timezone(timedelta(hours=9))
RULES = {"定例": ["定例", "週次", "朝会"], "1on1": ["1on1", "面談"], "社外": ["打ち合わせ", "商談", "様"]}
SKIP_TYPES = {"focusTime", "outOfOffice", "workingLocation"}


def category(title: str) -> str:
    for name, words in RULES.items():
        if any(w in title for w in words):
            return name
    return "未分類"


start = datetime.fromisoformat(sys.argv[1]).replace(tzinfo=JST)
end = datetime.fromisoformat(sys.argv[2]).replace(tzinfo=JST)
service = calendar()
events, page = [], None
while True:
    resp = service.events().list(calendarId="primary", timeMin=start.isoformat(), timeMax=end.isoformat(),
                                 singleEvents=True, orderBy="startTime", maxResults=250, pageToken=page).execute()
    events += resp.get("items", [])
    page = resp.get("nextPageToken")
    if not page:
        break

hours = defaultdict(float)
for e in events:
    if "dateTime" not in e.get("start", {}) or e.get("eventType") in SKIP_TYPES:
        continue  # 終日予定・集中時間・不在などは会議ではない
    if any(a.get("self") and a.get("responseStatus") == "declined" for a in e.get("attendees", [])):
        continue  # 自分が辞退した予定は除く
    s = datetime.fromisoformat(e["start"]["dateTime"])
    t = datetime.fromisoformat(e["end"]["dateTime"])
    week = (s.date() - timedelta(days=s.weekday())).isoformat()  # 週の月曜日
    hours[(week, category(e.get("summary", "")))] += (t - s).total_seconds() / 3600

Path("data").mkdir(exist_ok=True)
with open("data/meeting_hours.csv", "w", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    w.writerow(["week", "category", "hours"])
    for (week, cat), h in sorted(hours.items()):
        w.writerow([week, cat, round(h, 2)])
print(f"{len(events)} events -> data/meeting_hours.csv")

npm install -g @google/clasp
clasp login                      # ブラウザでGoogleアカウントにログイン（認証情報は ~/.clasprc.json に保存される）
# 事前に https://script.google.com/home/usersettings で「Google Apps Script API」をオンにする

mkdir -p gas/form-handler && cd gas/form-handler
clasp clone <スクリプトID>       # スクリプトIDは Apps Script エディタの「プロジェクトの設定」にある
# → .clasp.json / appsscript.json / Code.js などがローカルにできる

clasp pull                       # Google側の最新をローカルに反映
clasp push                       # ローカルの変更をGoogle側に反映（＝すぐ動くコードが変わる）

# CLAUDE.md（バックオフィス自動化）

## 基本方針
- Google のデータは scripts/read/ のスクリプトで取得する。API を直接叩くコードをその場で書いて実行しない
- 反映は scripts/write/ のスクリプトで行う。必ず --commit なしのドライランを人に見せ、OK をもらってから --commit
- secrets/ 配下は読まない・表示しない。認証エラーが出たら人に再認証を依頼する

## スプレッドシート
- 元シートは絶対に書き換えない。整形結果は sheet_clean.py が新しいシートに書く
- 整形ルールは drafts/clean_rules.json に提案する。空欄の扱い・金額の単位など業務の意味が絡む判断は、必ず人に質問する
- 合計・件数はスクリプトの出力を使う。自分で数え直した数字を書かない

## Gmail
- 分類カテゴリ: 見積依頼 / 請求・支払い / 契約・解約 / 採用 / その他
- 返信は drafts/replies.json に書く。宛先・件名は書かない（スクリプトが元メールから付ける）
- 価格・納期・契約条件など、社内で決まっていないことを約束しない。分からない点は「担当より改めてご連絡します」とする
- 「採用」カテゴリは返信下書きを作らず、件数だけ報告する（担当部署が対応）
- メールは送信しない。送信に使えるコードを書かない

## カレンダー
- 出力は集計値のみ。予定のタイトルや参加者名を drafts/ やレポートに書き写さない

## GAS（gas/ 配下）
- clasp push は必ずテスト用プロジェクトに先に行い、人の確認後に本番へ。clasp deploy はしない

{
  "permissions": {
    "allow": [
      "Bash(python scripts/read/sheet_profile.py:*)",
      "Bash(python scripts/read/gmail_fetch.py:*)",
      "Bash(python scripts/read/calendar_hours.py:*)",
      "Bash(clasp pull:*)",
      "Read(./data/**)",
      "Edit(./drafts/**)",
      "Edit(./gas/**)"
    ],
    "ask": [
      "Bash(python scripts/write/sheet_clean.py:*)",
      "Bash(python scripts/write/gmail_draft.py:*)",
      "Bash(clasp push:*)"
    ],
    "deny": [
      "Read(./secrets/**)",
      "Read(**/credentials.json)",
      "Read(**/token.json)",
      "Read(**/service_account.json)",
      "Read(~/.clasprc.json)",
      "Read(./.env)",
      "Edit(./scripts/**)",
      "Bash(clasp deploy:*)",
      "Bash(curl:*)",
      "Bash(cat:*)",
      "Bash(python -c:*)"
    ]
  }
}

> 「売上台帳」シートが表記ゆれだらけなので、整形して取引先別の売上集計とグラフを作って。

● Bash(python scripts/read/sheet_profile.py 売上台帳)
  ⎿ 9 columns / 1,284 rows -> data/profile.json
● Read(data/profile.json)
● Write(drafts/clean_rules.json)

  整形ルール案を drafts/clean_rules.json に作りました。確認したい点が2つあります。
  1.「金額」列に空欄が37行あります。0円として集計しますか？除外しますか？
  2.「取引先」の「ABC」は「株式会社ABC」と同一と見てよいですか？（「ABCトレーディング」は別扱いにしています）

> 空欄は除外。ABCは同一でOK。

● Edit(drafts/clean_rules.json)
● Bash(python scripts/write/sheet_clean.py drafts/clean_rules.json)
  ⎿ 元 1284 行 → 整形後 1261 行（重複除去 23 行） ...
● Bash(python scripts/write/sheet_clean.py drafts/clean_rules.json --commit)  ← 承認を求められる
  ⎿ written: 整形_20260926 集計_20260926

> 今週の「問い合わせ」ラベルのメールを分類して、返信の下書きを作って。

● Bash(python scripts/read/gmail_fetch.py 問い合わせ 7)
  ⎿ 14 messages -> data/inquiries.json
● Read(data/inquiries.json)
● Write(drafts/replies.json)

  14件を分類しました：見積依頼 6 / 請求・支払い 3 / 契約・解約 2 / 採用 1 / その他 2
  - 採用の1件は方針どおり下書きを作らず、件数のみ報告します
  - 見積依頼のうち2件は、希望納期が社内ルールで判断できないため
    「担当より改めてご連絡します」としています
  下書き13件の内容を確認してください。

> 契約・解約の2件目は、解約手続きのページURLを案内に入れて。あとはOK。

● Edit(drafts/replies.json)
● Bash(python scripts/write/gmail_draft.py drafts/replies.json --commit)  ← 承認
  ⎿ 13 drafts created（送信はGmailで人が行ってください）

---
name: inquiry-drafts
description: Gmailの「問い合わせ」ラベルのメールを分類し、返信の下書きを作る。問い合わせ対応、返信下書き、メールの振り分けを頼まれたときに使う。
---

# 問い合わせ返信下書きの手順

1. `python scripts/read/gmail_fetch.py 問い合わせ 7` を実行する
2. CLAUDE.md のカテゴリで分類し、カテゴリ別の件数を表で報告する
3. 「採用」以外について drafts/replies.json に返信本文を書く（宛先・件名は書かない）
4. 判断できなかった点（価格・納期・例外対応）を一覧にして人に確認する
5. 人の OK が出たら gmail_draft.py をドライラン → --commit の順で実行する
6. 最後に「送信は Gmail で人が行う」ことを伝える

#!/usr/bin/env bash
# 毎週月曜 8:00 に cron 等から実行。Gmailへの下書き作成（write）はしない
set -euo pipefail
cd "$(dirname "$0")/.."

claude -p "inquiry-drafts の手順1〜4を実行し、drafts/replies.json まで作って。gmail_draft.py は実行しないこと。" \
  --allowedTools "Bash(python scripts/read/gmail_fetch.py:*)" "Read" "Edit(./drafts/**)" \
  --output-format json > "logs/inquiry_$(date +%Y%m%d).json"