gmail-mcp

あなたのAIアシスタントのためのGmail — 複数のアカウントを同時に、あなた自身のサーバーで。

日本語版 · 简体中文

gmail-mcp は、Gmail を Claude やその他の MCP クライアントに接続します。検索・読み取り、引用履歴付きの送信・全員返信、転送、添付ファイルやインライン画像の処理、下書き・ラベル・スレッドの管理を、複数の Google アカウントで同時に行えます。

これはあなた自身の Cloudflare Worker 上のリモートサーバーとして動作するため、同じ接続がノートPCの Claude Code、ブラウザの claude.ai、スマホの Claude から応答します。各接続は1つの Google アカウントにサインインし、Google のリフレッシュトークンはあなたの Cloudflare アカウントに保持されます。

ここに来る理由は2つあります。Claude と Google に組み込まれている Gmail コネクタはメールの読み取りと下書き作成はできますが、送信はできず、アシスタントアカウントごとに1つの Google アカウントしか保持できません。送信できるサーバーは通常ローカルプロセスであり、机の上では問題ありませんが、スマホからは見えません。

比較

google_workspace_mcp は、ここで最も完全なプロジェクトです。Gmail だけでなく Workspace 全体をカバーし、Gmail の署名を追加し、添付ファイルを URL から直接取得しますが、gmail-mcp はどちらも行いません。shinzo-labs/gmail-mcp は、64のツールを通じて休暇応答、委任、S/MIME にアクセスします。これらは gmail.settings.* の下にあり、gmail-mcp が要求しないスコープであるため、権限がどうであれ、その範囲外にあります。

残りの大部分は、2つの設計上の違いで決まります。呼び出し引数でアカウントをルーティングすると、1つの権限ですべての接続済みメールボックスにアクセスできますが、メールボックスを接続に固定すると、誤った引数は何にも到達しません。また、読み取り時にローカルサーバーはすべてのパートを UTF-8 としてデコードします。ISO-2022-JP や Shift_JIS のメールは文字化けし、Gmail が添付ファイルのブロブとして保存する長いメッセージは本文が空で返されます。

Related MCP server: Gmail MCP Connector

デプロイ

約10分です。Cloudflare アカウント、bun、Google アカウントが必要です。Cloudflare アカウントのドメインは任意です — ない場合、Worker は workers.dev で応答します。

1 · Google OAuth クライアントを作成

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com

次の2つのステップには Google の API がないため、Cloud コンソールで行います。

• OAuth 同意画面 → 外部、次に 対象者 の下で アプリを公開 を押します。テスト状態のままにしておくと、Google はすべてのリフレッシュトークンを7日ごとに失効させ、各接続はトークンとともに失われます。公開すると、アプリはサインイン時に未確認アプリの警告を表示し、最大100アカウントに対応します。

• 認証情報 → 認証情報を作成 → OAuth クライアント ID → ウェブアプリケーション、承認済みのリダイレクト URI として https://<your-host>/callback を指定します。クライアント ID とシークレットは保管しておいてください。

<your-host> は Worker に向けるドメイン、または、そうでなければ割り当てられる workers.dev ホスト名です。先にデプロイしてから戻ってきてこれを入力しても問題ありません — Worker が / で提供するガイドに正確な値が表示されます。

2 · Worker をデプロイする

このボタンを押すと、リポジトリが GitHub アカウントにコピーされ、KV 名前空間と Durable Object が作成され、4つのシークレットが要求されます。workers.dev にデプロイされます。カスタムドメインは後で 設定 → ドメインとルート の下で追加します。

代わりにターミナルから:

git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp
bun install
bun run setup

bun run setup は応答するドメインを尋ね、OAUTH_KV 名前空間を作成または再利用し、クライアント ID とシークレットを受け取り、クッキーキーを生成してデプロイします。最初の2つの回答は wrangler.local.jsonc に保存され、これは git で無視されます — wrangler.jsonc にはどのアカウントの名前空間も誰のドメインも記載されていないため、クローンはどこにでもデプロイできます。単一のシークレットをローテーションするためにセットアップを再実行しても安全です。

3 · クライアントを接続する

クライアント ID とシークレットのフィールドは空のままにしてください — MCP クライアントは自分自身を登録します。

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Claude Code で /mcp を実行して、各接続をその Google アカウントにサインインさせます。claude.ai では 設定 → コネクタ → カスタムコネクタを追加 で同じ URL を指定します。/mcp/ の後には任意の単一セグメントのラベルを使用でき、これにより、URL を共有する2つのサーバーを拒否するクライアントに対して、1つのデプロイメントで複数のメールボックスを提供できます。

デプロイメントは https://<your-host>/ でこのガイドを提供します。

できること

whoami search_messages get_message get_thread get_attachment

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

メッセージはメールクライアントが送信するのと同じ方法で送信されます: HTML 代替付きのプレーンテキスト、ファイル添付、cid: で参照されるインライン画像が、multipart/mixed › multipart/related › multipart/alternative としてネストされます。件名と表示名は RFC 2047、ファイル名は RFC 2231 を使用するため、日本語、中国語、絵文字もそのまま送信されます。

reply_all は元のメールの Reply-To、From、To、Cc を読み取り、自分のアドレスと送信元として使用するアドレスを除外し、送信者が宛てたアドレスから返信し、References チェーンを引き継ぎ、送信する部分に元のメールを引用します。forward_message は転送されたエンベロープを再現し、元のメールのファイルを再添付できます。

replyToMessageId を指定した create_draft は、送信前に編集する下書きとして返信を作成します: 元のスレッドに参加し、In-Reply-To と References を引き継ぎ、全員返信の受信者と Re: 件名を導出し、元のメールを引用します。update_draft は指定されたフィールドのみを変更します。受信者、テキスト、任意のクライアントで手動で追加されたファイル、下書きが返信するスレッドは読み戻されて保持されます。base64 がツール引数に収まらないファイルは、代わりにステージングされます: stage_attachment_begin は生のバイトを1回の curl -T で受け取るアップロード URL を返し、stage_attachment_append は base64 をチャンクで受け取り、すべての attachments フィールドは結果の stagingId を受け入れます。

読み取りは意図的に制限されています: メッセージとスレッドの本文には文字数の予算があり、応答全体にはバイト数の上限があり、添付ファイルは十分に小さく読める場合にのみインラインで返されます。長いメーリングリストのスレッドや大きなファイルは、アシスタントのコンテキストを埋めるのではなく、その旨の注記付きで切り詰められて返されます。

仕組み

2つの OAuth フローが1つの Worker で合流します。MCP クライアントは Worker に対して認証し、Worker はあなたの代わりに Google に対して認証します。どちらの側も相手の認証情報を保持しません。

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

使用技術

• TypeScript on Cloudflare Workers — Durable Objects が各 MCP セッションを保持し、KV が OAuth グラントを保持

• Hono — OAuth エンドポイント、Google コールバック、/ のセットアップページのルーティング

• @cloudflare/workers-oauth-provider — MCP クライアントが登録する OAuth 2.1 サーバー

• agents — McpAgent、Durable Objects 上の MCP トランスポート

• @modelcontextprotocol/sdk と Zod — ツール定義と引数検証

• Bun、Biome、Wrangler — インストール、テスト、リント、デプロイ

Gmail 自体は REST API に対する通常の fetch で呼び出されます。公式の googleapis SDK は Node を前提としており、Worker が配布すべき量をはるかに超えるものを含むため、メッセージ構築、MIME 解析、トークン更新は代わりに src/gmail.ts と src/utils.ts にあります。

エンドポイント

サインインできるユーザー

ALLOWED_EMAILS が、Google が検証済みとして報告するアドレスに対してチェックして決定します — 同意後、グラントが存在する前です。

各グラントは認証したメールボックスのみに到達するため、このリストを広げても、すでに接続されているメールボックスへのアクセスが広がることはありません。* を設定すると、見知らぬ人があなたのデプロイメントと Google クライアントの割り当てを自分のメールに使用できるようになります。

制限

共有デプロイメントが枯渇しないようにするための2つの上限があり、どちらも wrangler.jsonc で設定されます:

Workers Free プランではさらに上限が適用されます: 1回の呼び出しにつき50件の送信リクエストです。広範囲の読み取りはメッセージごとに1回消費するため、search_messages と list_drafts はそこで maxResults を45以下にする必要があります。それを超えると、超過分は結果ではなくメッセージごとのエラーとして返されます。有料プランでは1000件まで許可されます。

どちらかを引き上げて再デプロイしてください。Cloudflare のレートリミッターはビルド時にバインディングから上限を読み取るため、各々の simple.limit がそれを変更する唯一の場所です。単一ユーザーのデプロイでは両方ともそのままにしておけます — 通常のアシスタント利用はそれらをはるかに下回ります。

セキュリティ

セルフホスティングは信頼の問題を移すだけで、なくすわけではありません。そこで、すべてがどこにあるのかを以下に示します。

• あなたのトークンはあなたのものです。 リフレッシュトークンは、あなたの KV 名前空間内の OAuth グラント内で暗号化されています。セッションの Durable Object は1時間有効なアクセス トークンを保持し、MCP エージェント フレームワークはオブジェクトが存続する間、リフレッシュトークンを含むグラントのコピーをそこに保持します。両方のストアはあなた自身の Cloudflare アカウントであり、保存時に暗号化されています。メールは決して保存されません — 通過するだけです。

• 1セッション、1メールボックス。 MCP セッションはそれを開いたアカウントにバインドされるため、あるメールボックスのグラントは、借用したセッション ID を通じて別のメールボックスに作用することはできません。

• スコープの最小化。 gmail.modify は読み取り、送信、ラベル、ゴミ箱をカバーします。完全な削除と gmail.settings.* のすべてを除外し、自動転送ルールとフィルターの外部持ち出し — 古典的なメールボックスのバックドア — を、盗まれたグラントでできることの範囲外に置きます。2つの読み取り専用スコープがそれに加えて要求されます: userinfo.email と userinfo.profile。これらは許可リストとセッション バインディングがどのアカウントがサインインしたかを知るためのものであり、メールには到達しません。

• ヘッダーはすり替えられません。 送信されるすべてのヘッダー値は、CR、LF、または NUL を含む場合に拒否されるため、どの引数も自身のフィールドから抜け出して別のフィールドを追加することはできません — たとえば件名行の中の Bcc など。メディア タイプは検証され、引用された履歴は HTML エスケープされます。これが行わないのは、引数自体を取り締まることです: bcc は実際のパラメータであるため、メッセージ本文に隠された指示に基づいて行動するモデルがそれを埋める可能性は依然としてあり、クライアントの承認プロンプトがそのチェックとして残ります。

• アクセスは取り消せます。 ALLOWED_EMAILS を狭めると、新しいサインインが停止します。単一アカウントのアクセスは myaccount.google.com/connections で取り消されます。Google クライアント シークレットをローテーションすると、すべてのグラントが一度に無効になります。

Worker はリクエストの処理中にメールをメモリ内で復号化します。これは、ホスト型リレーが必ず行うことです。特定のメールボックスにとってそれが受け入れられない場合は、そのメールボックス用にローカル MCP サーバーを実行してください。

テスト方法

253のユニット テストが、メッセージ構築 (MIME ネスト、RFC 2047 折り返し、RFC 2231 ファイル名、CR/LF 拒否、base64 ラッピング)、文字セットをまたぐ本文抽出、返信と転送の作成、Google トークン フロー、サインイン許可リスト、サインインのブラウザ側を保護する CSRF と状態バインディングのチェック、そして Gmail の代役に対するツール自体 — セッション所有権、受信者構成、添付ファイル選択、部分的に失敗した読み取りが返すもの — をカバーしています。

それに加えて、すべてのツールが実際の Gmail アカウントに対して実行され、別のアカウントが届いたものを確認しました:

開発

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

質問とバグ

issue を開いてください。

ライセンス

Copyright © 2026 mkpoli。MIT License の下で公開されています。

src/workers-oauth-utils.ts は cloudflare/ai 内の remote-mcp-github-oauth デモ から派生したもので、Copyright © 2025 Cloudflare, Inc.、MIT License の下で使用されています。THIRD-PARTY.md を参照してください。