multi-gmail-cowork-mcp

セルフホスト型の小型 MCP サーバーです。1つの Claude カスタムコネクタから、複数の独立して認証された Gmail アカウントを検索・閲覧・作成・送信できます。誰でも自分の Google Cloud プロジェクトにデプロイできるように作られており、共有インフラはゼロ、デプロイごとのコード変更もゼロです。

Claude Cowork
      |
      v
Your private Multi-Gmail MCP  (your own Cloud Run project)
      |
      +-- Gmail account: "personal"
      +-- Gmail account: "work"
      +-- Gmail account: "billing"
      +-- ...more, added any time via the admin page

Claude に次のようなことを依頼できます:

• 「仕事用の Gmail で David からのメールを検索して」

• 「接続済みのすべての Gmail アカウントで『invoice 4831』を検索して」

• 「ACH Works からの最新メールを読んで。どのアカウントで受信したかは問わない」

• 「昨日 John からメールを受信した Gmail アカウントはどれ?」

すべての結果は、それが取得されたアカウントのエイリアスとメールアドレスに明確に帰属します。接続されていないアカウントや、認証が期限切れになったアカウントを要求した場合は、明確なエラーが返ります。このサーバーが別のアカウントに黙って切り替えることは決してありません。

これは何ではないか

Gmail のみです。カレンダー、ドライブ、ドキュメント、スプレッドシート、連絡先はありません。完全削除ツールもありません。共有バックエンド、中央アカウント、テレメトリもありません。

Related MCP server: Gmail MCP

プライバシーモデル — 誰があなたのメールを見られるか

Google  <->  Your Google Cloud deployment  <->  Claude / Anthropic

• あなたが、あなた自身の Google Cloud プロジェクトに、あなた自身の Google OAuth クライアントとあなた自身の Cloud Run サービスを使ってデプロイします。

• Google が OAuth 許可を発行・取り消しできます。通常の OAuth トラフィックとして扱われます。

• あなたのデプロイ環境だけが、Gmail のリフレッシュトークンを保存する唯一の場所です。

• Claude/Anthropic は、Claude がツールを呼び出したときにツールが返す内容を見ます(他の MCP ツールと同じ)— それ以上でも、使用していないときに見ることもありません。

• このリポジトリの作者があなたのメールを見ることは、決してありません。 共有サーバーは存在しません。あなたのいとこのデプロイ環境とあなたのデプロイ環境に共通するのは、ソースコードだけです。

完全な信頼境界と設計根拠の解説 — 認証がなぜこのように実装されているのか、そしてこのプロジェクトの既知の制限を含む — は SECURITY.md をお読みください。この README ではその理由を繰り返しません。

アーキテクチャ概要

• 言語/ランタイム: Node.js 20+ 上の TypeScript。公式の @modelcontextprotocol/sdk と Google の google-auth-library を使用。

• トランスポート: Streamable HTTP(現在の MCP 推奨リモートトランスポート)。ステートレス — 各リクエストは独立して処理されるため、セッションアフィニティなしで Cloud Run 上でクリーンにスケールします。

• Claude <-> サーバー認証: PKCE/S256 を使用した MCP OAuth 2.1 認可コードフロー、動的クライアント登録、短命のアクセストークン、ローテーションするリフレッシュトークン、Secret Manager 内のデプロイメントローカル認可状態。

• サーバー <-> Google 認証: PKCE を使用した標準 OAuth 2.0。接続された Gmail アカウントごとに 1 つの許可。gmail.modify スコープ(読み取り、作成、送信、メールボックス変更。完全削除は不可)。

• アカウントストレージ: 小さな JSON 配列(エイリアス、メール、リフレッシュトークン)を保持する 1 つの Google Secret Manager シークレット。データベースはありません。

• 管理 UI: HTTP Basic Auth の背後にあるスタイルなしの HTML ページ数枚 — アカウントの接続または切断に十分なだけです。

前提条件

• Google アカウントと、課金が有効な Google Cloud プロジェクト(ブートストラップは、課金がリンクされていない場合に正確な課金ページを表示します)。

• カスタムコネクタをサポートする Claude プラン(Cowork/claude.ai への接続用)。

• デプロイに他に必要なものはありません:Google Cloud Shell には gcloud、curl、openssl、jq がすでに含まれています。

コストと課金

Cloud Run には課金が有効なプロジェクトが必要です。このデプロイメントは個人・小規模ビジネス向けに設計されています:最小インスタンス数 0(アイドル時にゼロへスケール)および最大インスタンス数 3。通常の使用 — 1 日あたり数回の検索、閲覧、送信 — は、Cloud Run の Google Cloud 常時無料枠内に十分収まるため、実際の継続コストは $0 です。これは保証ではありません:無料枠を超える持続的なリクエストのバーストが発生した場合は、通常の Cloud Run 料金が発生します。ブートストラップは、支出前に通知を受け取りたい場合に備えて、オプションの予算アラートリンクを表示します。

ワンコマンド Cloud Shell セットアップ(推奨)

1. 上のボタンを使用して、このリポジトリを Google Cloud Shell で開きます(GitHub の Open in Cloud Shell を使用することもできます)。

2. Cloud Shell が要求したら認証し、次を実行します:

./scripts/bootstrap.sh

このスクリプトは、プロジェクトの選択(または作成)を求め、課金を確認し、必要な API を有効にし、専用の Cloud Run ランタイムサービスアカウントを作成し、必要な Secret Manager ロールのみを割り当て、すべてのシークレットを作成し、Cloud Run をデプロイし、PASS/FAIL チェックを表示します。再実行しても安全です:既存のシークレット、アカウントレコード、OAuth 認証情報、Cloud Run サービスは保持されます。

このスクリプトは、パスワード、OAuth クライアントシークレット、リフレッシュトークン、アカウントストア JSON、MCP OAuth トークンを決して出力しません。シークレット値は正確なバイトとして書き込まれます(末尾改行の認証情報バグなし)。読み取り専用の Cloud Shell 前提条件チェックには ./scripts/bootstrap.sh --check を使用してください。

避けられない Google ブラウザ手順が 1 つ

Google は、汎用 Web OAuth クライアントを作成するための安全でサポートされた API/CLI 操作を提供していません。ブートストラップが要求したら、表示された Google Auth Platform ページを開いて、次の操作を行います:

• アプリを 外部 として構成し、スコープ https://www.googleapis.com/auth/gmail.modify を追加し、テストユーザーとして使用する Gmail アドレスを追加します。

• アプリケーションタイプ Web アプリケーション で OAuth クライアントを作成します。

• スクリプトが表示する正確なコールバック URI を入力します: https://<your-cloud-run-host>/oauth/google/callback。

• 結果のクライアント ID とクライアントシークレットを、Cloud Shell の非表示プロンプトに貼り付けます。

Google が未検証アプリの警告を表示した場合、これは個人デプロイでは想定どおりです。テストモードの 7 日間制限を超えてリフレッシュトークンを有効に保つ場合は、同意画面を 本番環境 に公開してください。個人・小規模デプロイでは検証は不要です。

最後に、ブートストラップは管理 URL、正確な Google OAuth コールバック URL、MCP URL、次の人間のアクションを表示します。Claude はサポートされている OAuth フローを通じて MCP エンドポイントに認証します。コピーして URL に入れる静的なコネクタヘッダーはありません。

Gmail アカウントを接続する

1. ブートストラップが最後に表示したコマンドで、管理パスワード(ブートストラップが生成し、決して出力しない)を取得します:

   gcloud secrets versions access latest --secret=admin-password --project=YOUR_PROJECT_ID

   次に、表示された管理 URL を開き、ユーザー名 admin とそのパスワードでサインインします。

2. personal や work などの短いエイリアスを入力し、Add Gmail Account をクリックして、Google 認証を完了します。認証 URL は consent select_account を要求するため、Google は毎回アカウント選択画面を表示します。コールバック後に表示されるアドレスは、Google が実際に認証したアドレスです。エイリアスフィールドから取得されるわけではありません。

3. 必要な数の Gmail アカウントについて繰り返します。各エイリアスは独立しており、すべての結果はエイリアスと検証済み Gmail アドレスの両方に帰属します。

Claude Cowork を接続する

Claude で、Settings → Connectors → Add custom connector を開き、正確に入力します:

1. Connector name: Multi Gmail

2. Remote MCP URL: /claude-mcp で終わる表示された URL

3. OAuth Client ID: 空白のまま(サーバーは動的クライアント登録をサポート)

4. OAuth Client Secret: 空白のまま

/mcp ルートは既存のクライアント用に引き続き利用可能です。新しい Claude コネクタには /claude-mcp を使用して、その OAuth リソース ID が古いコネクタレコードから独立するようにしてください。

Add をクリックし、次に Connect をクリックします。Claude は MCP 認可メタデータを検出し、自身を登録し、デプロイ環境の Authorize MCP access ページを開きます。そこでユーザー名 admin と、自分の admin-password Secret Manager シークレットに保存されている管理パスワードでサインインし、承認します。Claude は https://claude.ai/api/mcp/auth_callback のコールバックを通じてリダイレクトし、OAuth トークンを保存して、再接続します。Gmail の OAuth クライアント ID やシークレットを Claude に入力しないでください — これらは Google の Gmail セットアップにのみ属します。

コネクタが接続されたら、Claude に list_accounts を呼び出すよう依頼し、各アカウントでエイリアス固有の検索を実行し、search_all_accounts で帰属を確認します。

デプロイ環境を検証する

scripts/acceptance_test.mjs は、すべてのツールが自分のデプロイ環境に対してエンドツーエンドで動作することを証明します — アカウント分離、不正なエイリアスでのフォールバックなし、下書き、到着と正しい From ID による送信。実際のリモートクライアントとして完全な MCP OAuth フローを実行し、トークンを決して出力しません:

MCP_BASE_URL=https://your-service.run.app \
  MCP_ADMIN_PASSWORD='...'   # Secret Manager -> admin-password
  node scripts/acceptance_test.mjs

送信テストは、アカウント A → アカウント B とアカウント B → アカウント A の 1 通ずつを送信するため、受信者は常に自分が所有するアカウントです。送信をスキップするには SKIP_SEND=1 を設定します。

ローカル開発(オプション)

ソース開発専用に、Node.js 20+ をインストールし、npm install を実行し、.env.example を .env にコピーし、TOKEN_STORE=file を設定し、npm run dev を使用します。ローカル Gmail OAuth には、http://localhost:8080/oauth/google/callback などの別の OAuth クライアントコールバックが必要です。本番シークレットを再利用したりコミットしたりしないでください。Windows ユーザーは、Cloud Shell ブートストラップの代わりに scripts/setup.ps1 と scripts/deploy.ps1 を使用できます。

アカウントの再認証 / 取り消し

以前の読み取り専用リリースからアップグレードした後、既存の各アカウントは Needs Gmail permission upgrade とマークされます。/admin を開き、同じエイリアスで Reauthorize をクリックし、Google の同意画面を完了します。コールバックは、そのエイリアスの保存済みリフレッシュトークンを置き換える前に、Google が実際に https://www.googleapis.com/auth/gmail.modify を許可したことを検証します。それまでは、読み取りツールは古い許可で引き続き動作し、書き込みツールは明確な再認証メッセージを返します。他のエイリアスが使用されることは決してありません。

アクセスを削除するには、アカウントの横にある Disconnect をクリックします。これにより、Google への許可が(ベストエフォートで)取り消され、資格情報ストアから即座に削除されます — その後、そのエイリアスが要求された場合、Claude は明確な「接続されていません」エラーを受け取り、黙ってフォールバックすることは決してありません。

Google 側でアクセスを取り消した後に同じエイリアスを再接続するには、同じエイリアスで Connect account を使用します — Google 認証が成功した後にのみ古いレコードを上書きします。

書き込みツールと安全性

デプロイされたサーバーは create_draft と send_email を公開します。どちらも明示的な接続済みアカウントのエイリアスを必要とし、別のアカウントにフォールバックすることは決してありません。send_email は常に選択された Gmail ID から送信し、結果にはその検証済みアドレスが含まれます。ツールは、より広い mail.google.com スコープではなく gmail.modify を使用し、完全削除ツールはありません。Claude コネクタの権限では、読み取りツールを自動的に許可し、create_draft と send_email は Needs approval に設定したままにする必要があります。

更新とローテーション

• デプロイ環境の更新: ソースを変更した後、または新しいシークレットバージョンを取得するには、./scripts/bootstrap.sh を再実行します(べき等 — アカウント、トークン、OAuth クライアントを保持)。Windows では scripts/deploy.ps1。既存の Gmail 接続と Claude コネクタは影響を受けません。

• 管理パスワードのローテーション: admin-password に新しい Secret Manager バージョンを追加し、再デプロイします。既存の Claude コネクタトークンは有効なままです(管理パスワードから派生していません)。将来の MCP 同意承認のみが新しいパスワードを使用します。

• oauth-state-secret のローテーション: これはすべての MCP OAuth トークンに署名するため、ローテーションすると Claude コネクタの既存トークンが無効になります — その後 Claude を再接続してください。保留中の Gmail リンク状態トークン(有効期間 10 分)も無効になります。接続済みの Gmail アカウントは影響を受けません。

• Gmail アカウントの許可のローテーション: 管理ページからエイリアスを再接続します(アカウントの再認証 / 取り消し を参照)。

すべてを削除する方法

• Gmail へのアクセスを削除: /admin から各アカウントを切断するか、https://myaccount.google.com/permissions で直接アクセスを取り消します。

• デプロイを削除:

  gcloud run services delete multi-gmail-mcp --region us-central1
  gcloud secrets delete mcp-oauth-state admin-password oauth-state-secret google-client-id google-client-secret gmail-mcp-accounts
  gcloud iam service-accounts delete multi-gmail-mcp-run@YOUR_PROJECT_ID.iam.gserviceaccount.com

• OAuth クライアントを削除: Cloud Console -> APIs & Services -> Credentials -> OAuth クライアント ID を削除し、必要に応じて OAuth 同意画面の設定も削除します。

• または最も簡単な方法: Google Cloud プロジェクト全体を削除します。

トラブルシューティング

• "Account needs to be reconnected" エラー: 保存されたリフレッシュ トークンが Google に拒否されました (取り消された、期限切れ、または同意画面が「Testing」のままである — 下記参照)。 /admin から再接続してください。

• リフレッシュ トークンが約7日で失効し続ける場合: OAuth 同意画面がまだ「Testing」公開ステータスのままです。「In production」に公開してください (手順 3 を参照) — 未検証のままで構いません。個人利用には問題ありません。

• Claude がコネクタに到達できない / 接続が静かに失敗する場合: サービス URL が別のホストへのリダイレクトなしで通常の HTTPS 経由で解決されることを確認し、Claude で /claude-mcp で終わる MCP URL を開いて Connect をもう一度クリックしてください。アクセストークンなしで呼び出された場合、サーバーは OAuth メタデータと 401 チャレンジを返す必要があります。静的リクエストヘッダーは不要です。

• gcloud run deploy が有効になっていない API で失敗する場合: scripts/setup.ps1 を再実行するか、gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com gmail.googleapis.com iam.googleapis.com を実行してください。

• ローカル開発環境が HTTPS で Google に到達できない場合 (証明書エラー): これはほとんどの場合、ローカルマシンの問題です (企業のプロキシやウイルス対策ソフトによる TLS 傍受)。このプロジェクトのバグではありません。マシンの信頼されたルート証明書を確認してください。

Google OAuth の Testing と長期的な利用

Google Cloud の OAuth クライアントは、公開ステータスが Testing から始まります。Testing の間、機密/制限付きスコープ (gmail.modify を含む) のリフレッシュ トークンは、ユーザーが何人であっても 7日 で期限切れになります。そのままにしておくと、コネクタが毎週静かに壊れます。

修正方法は Google の審査 (公開 SaaS 向けの数か月かかるプロセス) ではありません。もっと簡単です: Publish app をクリックして同意画面を In production に移動します。gmail.modify のみを要求し、接続される Google アカウントの合計が 100 未満のアプリの場合、Google 自身のドキュメントでも、これは完全にサポートされている個人/小規模なユースケースとして扱われます — 審査は不要です。唯一の見える影響は、新しく接続された各アカウントが、同意する前に一度だけ "Google hasn't verified this app" というクリックスルー警告を表示することです。その警告は想定内であり、設定が間違っていることを意味するものではありません。根拠となるルールと情報源については SECURITY.md を参照してください。

リポジトリ構成

src/            TypeScript source (server, MCP tools, admin/setup UI, OAuth flows)
scripts/        bootstrap.sh (Cloud Shell), setup.ps1/deploy.ps1 (Windows),
                acceptance_test.mjs (verify any deployment end-to-end)
.env.example    Local-dev configuration template (placeholders only)
SECURITY.md     Trust model, design rationale, known limitations

ライセンス

MIT — LICENSE を参照してください。