NexusAGYmail

NexusAGYmail

Google Antigravity 向けの Gmail。安心して任せておけます。 Antigravity のストアには Gmail コネクターがありません。ローカル MCP サーバー nexus-agymail を使えば、公式 Gmail API 経由で Gmail を利用できます。検索、閲覧、添付ファイル、下書き、 ラベル、元に戻せるゴミ箱に対応し、下書きの送信はその下書きに対して明示的に承認した後に限られます。永久に削除されることはありません。

• Google 公式 Gmail MCP サーバーと同じツール（search_threads、get_message、get_thread、 create_draft、label_message など）を提供するため、一方を知っているエージェントならもう一方も使えます。Workspace Developer Preview への登録やリモート MCP エンドポイントの有効化は不要です。個人用 Gmail であれば、どのアカウントでもお使いのマシン上で実行できます。
• プロンプトではなくコードに組み込まれた安全策：メールをきっかけに送信が行われることはなく、すべてのメールはデータとして扱われ、メール内に隠された指示にはフラグが付けられます。添付ファイルは安全に保存され、秘密情報が添付されることはありません。
• Windows（毎日使用）と Linux（CI でユニットテスト）に対応しています。macOS でも動作するはずですが、テストされていません。トークンは Windows では DPAPI で暗号化され、それ以外では本人だけが読み取れるファイルに保存されます。クライアントに送信される内容はすべて英語です。

Nexus ファミリーの一員です：NexusWindows、 NexusBrowser、NexusAndroid。

クイックスタート

uv と Google アカウントが必要です。一度だけ、約 5 分で完了します。

1. ガイドに沿ってセットアップします：

   uvx --python 3.14 nexus-agymail setup
   

   Antigravity に nexus-agymail プラグインを追加し、続いて Gmail への接続を案内します。Gmail のスコープには制限があるため、すべてのユーザーが自身の Google Cloud プロジェクトで無料の OAuth クライアントを作成します。メールが他の誰かのアプリを経由することはありません。アシスタントは各 Google ページを適切な場所でブラウザーに開き、どこをクリックするか案内します（最初に接続する Gmail アドレスを尋ね、そのアカウントでページを開きます）。

   1. プロジェクトを作成します（名前は NexusAGYmail にします）。
   2. Gmail API を有効にします。
   3. 同意画面（Get started、External）を設定します。Branding では、ホームページ、プライバシーポリシーへのリンク、承認済みドメインを設定します（アシスタントがこのリポジトリ、その プライバシー セクション、github.com を提示します。Google では公開前にこれらが必要です）。次に Publish app をクリックします（未公開のままでは、Google が Error 403: access_denied でサインインをブロックします）。
   4. Desktop app タイプのクライアントを作成します（Use this client for an AI-powered agent はオフのままにします）。次に Download JSON をクリックします。アシスタントがダウンロードフォルダーからファイルを自動で見つけます。
   5. サインインします。Google に「Google hasn't verified this app」と表示されます。これはご自身のアプリなので、Advanced > Go to NexusAGYmail (unsafe) をクリックします。

   次に、確認可能な項目をチェックします。Gmail API から応答があり、アプリが実際に公開されていること（Testing のままのアプリでは、Google が 7 日間有効のサインインを返します）を確認します。公開されていない場合は、修正するページを開いて、もう一度サインインします。

2. Antigravity を再起動します。

   セットアップを省略する場合の Antigravity の手動設定（mcp_config.json）

   {
     "mcpServers": {
       "nexus-agymail": { "command": "uvx", "args": ["--python", "3.14", "nexus-agymail@latest"] }
     }
   }
   

たとえば、「今週届いた未読メールを要約して」「1 か月以上前のニュースレターをアーカイブして」「Alice からの最新メールに、同意するという返信を作成して、送信する前に見せて」と頼んでみてください。

Desktop app クライアントの JSON をすでにお持ちですか？ uvx --python 3.14 nexus-agymail auth --client-secret <file> を実行すると、コンソールでの手順を省略できます。uvx --python 3.14 nexus-agymail status を実行すると、トークンの保存場所と、トークンが持つスコープを確認できます（シークレットは表示されません）。

クライアントを作成したくない場合は？ Google 公式の Gmail MCP サーバー は Google 側で動作し（ツール名は同じです）、デベロッパー プレビューとして提供されています。ただし、Google Workspace Developer Preview Program への参加と Google Cloud プロジェクトが必要で、メールの送信はできません。NexusAGYmail は、Antigravity に独自の Gmail コネクターがなく、送信前の確認を経たメール送信を可能にするために作られました。

仕組み

flowchart LR
    A[Google Antigravity] -- MCP stdio --> S[nexus-agymail<br/>on your machine]
    S -- HTTPS, official Gmail API v1 --> G[(Gmail)]
    S -. token, encrypted .- T[~/.nexus/nexus-agymail]
    S -. attachments .- D[Downloads/NexusAGYmail]

このサーバーは、シンプルなローカルプロセスです。クラウドリレーもブラウザーの自動操作もありません。ご自身の OAuth クライアントと、マシン上に保存されたリフレッシュトークンを使って gmail.googleapis.com と通信し、トークンの更新には oauth2.googleapis.com を使用します。

ツール

名前とパラメーターは、Google の公式 Gmail MCP サーバー およびその拡張機能（update_draft、trash_*）に準拠しており、独自のツールが 3 つあります。send_draft、download_attachment、 auth_status です。

ツール	機能
search_threads	スレッドを検索します（Gmail 構文）。1 回の呼び出しにつき 1 ページです。pageSize は 1～50（デフォルトは 20）、pageToken を指定します。各スレッドには messageCount と直近 5 件のメッセージの概要が含まれます。includeTrash でゴミ箱を含められます。迷惑メールは常に除外されます
get_message	1 件のメッセージを取得します。ヘッダー、テキスト形式の本文（HTML を変換）、添付ファイル一覧（part_id、名前、種類、サイズ）が含まれます。maxChars（デフォルトは 8,090）
get_thread	スレッドを順番に取得します。以前の返信の引用は削除され、その旨が報告されます。maxChars は共有されます（デフォルトは 16,180）
download_attachment	添付ファイル（partId）を Downloads/NexusAGYmail または絶対パスの directory に保存します。ファイル名はサニタイズされ、上書きは行わず、インターネットからダウンロードしたファイルとしてマークされます。パス、サイズ、SHA-256 を返します
list_labels	ラベル（ID、名前、種類）を取得します。システムラベルが先に表示されます
create_label	ユーザーラベルを作成します（displayName、A/B は階層化を示します）。親ラベルが存在しない場合は、autoCreateParentLabels=false でない限り、親ラベルも作成されます。既存のラベルはそのまま返され、システムラベルの作成は拒否されます
create_draft	下書きを作成します。to、cc、bcc はリストまたはテキストで指定します。返信として作成する場合（replyToMessageId または threadId）、In-Reply-To、References、「Re:」を設定し、同じスレッドに追加します。attachments（絶対パス、合計 25 MB）
list_drafts	下書きを取得します。1 回の呼び出しにつき 1 ページ（1～100 件）です。query で絞り込めます
get_draft	1 件の下書きを取得します。宛先、件名、テキスト形式の本文、添付ファイル、返信ヘッダーが含まれます。maxChars（デフォルトは 8,090）
update_draft	下書きを書き換えます（空のフィールドは変更されません）。スレッド、返信、添付ファイルは保持されます。attachments で追加し、removeAttachments で名前を指定して削除します
label_message / unlabel_message、label_thread / unlabel_thread	labelIds にはシステム ID（INBOX、UNREAD、STARRED、IMPORTANT、CATEGORY_*）、ユーザーラベルの ID または名前を指定します。アーカイブするには INBOX を削除します。不明なラベルはエラーになります。createMissing=true の場合にのみ作成されます。ID は単一またはリストで指定でき、上限は 100 件です
trash_message / trash_thread、untrash_message / untrash_thread	ゴミ箱に移動します。30 日間は元に戻せます。上限は 100 件です
send_draft	confirm を指定しない場合、ユーザーに表示する概要と、該当する下書きに紐付いた accord トークンを返します。confirm=true とそのトークンを指定した場合にのみ送信され、下書きは再度読み込まれ、変更されていないことが確認されます
auth_status	トークンの保存状況、許可されたスコープ（起動時に確認）、有効性を確認します。スコープの不足または余分なスコープがある場合は reauth_required になります

すべてのツールには MCP アノテーション（タイトル、読み取り専用、破壊的操作、冪等性）が付与されています。Antigravity では、setup によって、各ツールの用途と、代わりにブラウザーを使用する場面（Gmail の設定（フィルターや署名など）、別の Google アカウント）を説明する短いスキルもインストールされます。

セーフガード

• スコープ：gmail.readonly、gmail.compose、gmail.modify。https://mail.google.com/ は決して使用しません。これは完全削除を許可する唯一のスコープです。delete、batchDelete、ゴミ箱を空にするツールはなく、その点はコードでテストされています。古いトークンに gmail.modify がなくても、読み取りと下書きの作成は引き続き行えますが、ラベル付けツールとゴミ箱ツールは Gmail を呼び出さずに scopes を返します。
• 送信：send_draft(draftId, confirm=true, accord=<token>) のみを使用します。ユーザーがその下書きについて明示的に承諾した後に限り、メールの指示によって送信することはありません。1回限りのトークン（10 分間有効）は要約で返され、宛先（to、cc、bcc）、件名、本文全体、すべてのパート（HTML を含む）、各添付ファイルの SHA-256 に対して紐付けられます。送信の直前に下書きを再度読み込み、何か変更されていれば送信せず、新しい要約を返します。送信呼び出しは drafts.send のみで、下書きを使わない直接送信はありません。
• 出所：エージェントが読んだメールから見つかった宛先は、要約で provenance として示されます。ユーザーが依頼した場合に限り使用できます。
• プロンプトインジェクション：件名、スニペット、本文、アドレス、添付ファイル名は ⟦mail:ID …⟧ … ⟦/mail:ID⟧ で囲み（回答ごとにランダムな ID を使用）、データとしてラベル付けして返します。非表示の HTML テキストと不可視文字は削除されます。AI に向けた指示のように見えるメールには injection_warning フィールドが付与されます（これはシグナルにすぎず、何かをブロックしたり許可したりするものではありません）。
• 添付ファイル：受信したファイルは、無害化したファイル名（パス、禁止文字や不可視文字、「fdp.exe」のような右から左への上書き文字、Windows の予約名を処理）で保存され、既存ファイルを上書きすることはありません。また、Windows の「インターネットからダウンロードされたファイル」マーク（Zone.Identifier）が付与されるため、Windows と Office は保護機能を適用して開きます。ローカルファイルを添付する際は、シークレットが保存されている場所（.ssh、.gnupg、.aws、.config/gcloud、AI アプリのフォルダー、.env ファイル、秘密鍵、credentials.json など、および NEXUS_AGYMAIL_PROTECTED に列挙した独自のフォルダー）からは添付しません。ユーザーはいつでも Gmail で自分で添付できます。
• トークン：~/.nexus/nexus-agymail/token.bin に保存し、現在の Windows アカウントの DPAPI で暗号化します（アクセス権もそのアカウントに制限）。macOS と Linux では 0600 ファイルとして保存します。ロック下でアトミックに書き込まれるため、複数のサーバーを同時に実行できます。トークンが表示されることはありません。再度サインインする際、追加スコープを持つ以前のトークンは、新しいトークンの保存後にのみ失効させます。
• 正確なエラー：トークンの失効または期限切れ、ネットワーク、クォータ、権限、見つからない項目、ラベルの各エラーには、安定した code（revoked、network、quota、forbidden、not_found、label、invalid_argument など）が割り当てられます。すべてのリクエストは 429 および 5xx で指数バックオフによる再試行を行います。バッチリクエストでは、クォータ超過で拒否された項目のみを再試行します。
• サイズの上限：本文は maxChars で切り詰められ（切り詰めたことを報告）、検索結果はページ分割され、ラベル付けまたはゴミ箱への移動は 1 回あたり最大 100 項目です。

設定

変数	用途
NEXUS_AGYMAIL_HOME	~/.nexus/nexus-agymail の代わりに使用する状態フォルダー（トークン、OAuth クライアント、バックアップ）
NEXUS_AGYMAIL_CLIENT_SECRET	auth --client-secret で作成したコピーの代わりに使用する OAuth クライアント JSON のパス
NEXUS_AGYMAIL_PROTECTED	ファイルを添付しない追加フォルダー（Windows では ;、それ以外では : で区切ります）
NEXUS_AGYMAIL_ACCOUNT	トークンにアドレスが含まれていない場合に auth_status が表示するアドレス
NEXUS_AGYMAIL_UPDATE_CHECK	0 に設定すると、PyPI で最新バージョンを毎日確認する機能を無効にします

プライバシー

NexusAGYmail はお使いのマシン上で動作します。独自のアカウント、テレメトリ、アナリティクス、リレーはありません。ネットワークリクエストの送信先は Google（gmail.googleapis.com、oauth2.googleapis.com、およびサインイン時にブラウザーでアクセスする accounts.google.com）のみで、お使いの OAuth クライアントを使用します。また、最新バージョン番号を取得するため、pypi.org へのリクエストを最大で 1 日に 1 回送信します（NEXUS_AGYMAIL_UPDATE_CHECK=0 で無効になります）。

• 読み取るデータ：エージェントが要求したメール、スレッド、下書き、ラベル、添付ファイルを、対応するツールが呼び出された場合に限って読み取ります。ローカルファイルは、エージェントが下書きに添付した場合に限って読み取ります。
• 送信先：ツールの結果は、接続した AI クライアントに送信されます。AI クライアントは独自のプライバシーポリシーに従って、その結果をモデルプロバイダーに送信する場合があります。下書きと送信済みメールは Gmail に送られます。NexusAGYmail がそれ以外の場所にデータを送信することはありません。
• 保存するデータ：~/.nexus/nexus-agymail/（または NEXUS_AGYMAIL_HOME）に、リフレッシュトークン（token.bin。Windows では DPAPI で暗号化され、それ以外では 0600 のファイル）、そのロックファイル、お使いの OAuth クライアントのコピー（client_secret.json）、および Antigravity の設定ファイルのバックアップ（setup による編集前のファイル。backups/）を保存します。また、Nexus アプリ用に ~/.nexus/status/agymail.json（インストール済みバージョンと最新バージョン、最終確認日時）も書き込みます。保存を要求した添付ファイルは、~/Downloads/NexusAGYmail（または指定されたフォルダー）に保存します。サーバーの実行中のみ、保留中の送信承認と、読み取ったメールで確認されたアドレス（provenance 警告用）をメモリー上に保持します。添付ファイルとして保存しない限り、メールがディスクに書き込まれることはありません。メールのログも保持しません。
• 削除方法：~/.nexus/nexus-agymail/ と、Antigravity をお使いの場合は ~/.gemini/config/plugins/nexus-agymail/ を削除します。Google アカウントのアクセス権を取り消し、不要になった場合は Google Cloud プロジェクトも削除してください。

既知の制限事項

• 各ユーザーが setup の案内に従って独自の Google OAuth クライアントを作成します。共用の公開クライアントには、Google による制限付きスコープの検証とセキュリティ評価が必要になります。
• 書き込み時に対応するのはプレーンテキストの本文のみです。create_draft と update_draft は HTML を書き込みません。update_draft は、Gmail で作成した下書きの HTML 部分をプレーンテキストで置き換えます。
• Gmail の設定（フィルター、署名、転送、不在返信）には対応していません。Gmail のウェブアプリをお使いください。
• 意図的に、迷惑メールの報告と完全削除には対応していません。
• Windows 11 と実際の Gmail アカウントで日常的に使用しています。Linux では CI で起動テストと単体テストを実行しています。macOS ではテストしていません。

開発

./test.ps1    # ruff, pyright, unit tests against a fake Gmail API (no network, no Google account)

test.ps1 は各チェックアウトに専用のテスト環境を ~/.nexus/nexus-agymail 以下に作成し、何もダウンロードしません。ネットワークに接続できる状態で uv sync --frozen を一度実行し、uv キャッシュを埋めてください。偽の Gmail API（tests/fake_gmail.py）は、実際の google-api-python-client と HTTP で通信するため、バッチ処理、再試行、アップロード、ページネーションを実際にテストできます。

ライセンス

MIT。Google とは提携していません。Gmail は Google LLC の商標です。