gmail-mcp

Gmail remote MCP — read + draft only, no send (TypeScript / Hono / Cloudflare Workers).

「読み取り＋下書きまで、送信は人間」を実装レベルで強制する Gmail remote MCP サーバー。

• エンドポイント: https://gmail-mcp.ippoan.org/mcp（claude.ai / Claude Code のカスタムコネクタ URL）

• 稼働 worker: gmail-mcp-staging（staging=prod パターン、ci-dashboard と同じ）

設計原則

• send 系ツールは実装しない。 messages.send / drafts.send に到達する経路をサーバーに一切置かない。スコープ上は送信可能なトークン（gmail.modify）だが、MCP サーバーが送信エンドポイントを公開しないため Claude 経由の送信経路が存在しない。CI の snapshot テストが send 系ツール名の混入を弾く

• 削除系は delete_draft（下書き）のみ。 メッセージ/スレッドの完全削除はもちろん、TRASH / SPAM への移動も modify_labels が拒否する（Gmail API に届く前にバリデーション）

• マルチアカウント: 全ツールに account?: string（エイリアス、省略時 "default"）。公式 Gmail コネクタの「1 アカウントのみ」制限を超えるのが動機の一つ

• メール本文は信頼しない: 本文経由の prompt injection に対する最大の緩和策が「送信不可」設計そのもの。下書きは必ず人間が Gmail UI で確認してから送信する

Related MCP server: gmail-mcp-server

ツール（v1）

認証の2層構造

Claude ──[① binding_jwt]──▶ gmail-mcp ──[② Google OAuth]──▶ Gmail API

1. コネクタ認証 — auth-worker（AUTH_WORKER_ORIGIN=https://auth-staging.ippoan.org が実稼働 AS）の binding_jwt を /mcp/introspect へ転送して検証。worker 側に shared secret 不要・fail-closed。CF Access は host を me で保護し /mcp のみ bypassAll（org 標準パターン）

2. Gmail 認可 — ブラウザで /oauth/start?alias=<name> → Google 同意（gmail.modify, offline+consent）→ /oauth/callback が refresh_token を KV に保存。CSRF は KV の state nonce（TTL 600s・one-shot）

トークンの置き場

access_token は保存せず都度 refresh（1h 有効）。

7 日失効の運用（テストモード、許容済み）

OAuth 同意画面はテストモードのまま運用する（本番公開・検証手続きはしない）。refresh token が失効すると各ツールが再認証 URL（/oauth/start?alias=<name>）を返すので、ブラウザで 1 分の再認可で復帰する。

アカウントの追加

1. Google Cloud Console → OAuth 同意画面（テストモード）の テストユーザーに対象 Gmail を追加

2. ブラウザで https://gmail-mcp.ippoan.org/oauth/start?alias=<新しいalias> を開いて認可

3. list_accounts で確認。以降ツールの account: "<alias>" で指定

セットアップ（新規に立てる場合の要点）

• GCP: プロジェクトに Gmail API 有効化、OAuth クライアント（Web 型、redirect URI https://gmail-mcp.ippoan.org/oauth/callback）

• secrets: gmail-mcp-google-client-secret を GCP SM に投入 → secrets-inventory sync_from_gcp で CF Secrets Store へ

• CF Access: host を me で保護 + /mcp を bypassAll

• auth-worker: MCP_RESOURCE_ORIGINS_ALLOWLIST に https://gmail-mcp.ippoan.org を登録（slug = gmail-mcp）

• deploy は CI（frontend-ci.yml worker 型、PR ごとに staging deploy → auto-merge）

開発

npm install         # 要 NODE_AUTH_TOKEN (read:packages)。無い場合は下記
npm run typecheck
npm test
npx wrangler dev

ローカルに GitHub Packages の token が無い場合は、@ippoan/mcp-cf-workers が TS ソース直配布（public repo）であることを利用して一時的に git spec で入れる:

npm pkg set "dependencies.@ippoan/mcp-cf-workers=github:ippoan/mcp-cf-workers"
npm install
# 作業後、commit 前に戻す
npm pkg set "dependencies.@ippoan/mcp-cf-workers=dev"

注意（stateless MCP）: deploy でツールが増えても接続済みコネクタの tools/list は 固定のまま。コネクタを再接続すると反映される。