NexusAGYmail

Why NexusAGYmail

Windows 10 and 11 (x64 and Arm64): one self-contained executable, nothing else to install (no Python, no .NET runtime). Everything sent to the client is in English. The same tools work without enrolling in the Workspace Developer Preview or enabling a remote MCP endpoint: it runs on your machine, with any personal Gmail.

Quick start

You need Windows 10 or 11 and a Google account. About 5 minutes, once.

[!TIP] Let your AI install it. Paste this into Claude Code, Codex or Antigravity:

text

Install NexusAGYmail by following https://raw.githubusercontent.com/pironjulien/NexusSystem/main/INSTALL-AI.md

Or use the NexusSystem app from the Microsoft Store (winget install --id 9NSH2P3QLWT1 --source msstore). New versions are no longer published to PyPI (0.13.0, the last Python version, stays available there).

$r = 'https://github.com/pironjulien/NexusAGYmail/releases/latest/download'Invoke-WebRequest "$r/get.ps1" -OutFile get.ps1Invoke-WebRequest "$r/SHA256SUMS.txt" -OutFile SHA256SUMS.txt(Get-FileHash get.ps1 -Algorithm SHA256).Hash   # must match the get.ps1 line of SHA256SUMS.txtgh attestation verify get.ps1 --repo pironjulien/NexusAGYmail   # optional: build provenancepowershell -NoProfile -ExecutionPolicy Bypass -File .\get.ps1 -Auth

Connect Gmail (guided, once)

Gmail scopes are restricted, so every user creates their own free OAuth client in their own Google Cloud project: your mail never goes through anyone else's app. The assistant (get.ps1 -Auth) opens each Google page in your browser at the right place and says what to click (it first asks which Gmail address to connect, so the pages open on that account):

1. create a project (name it NexusAGYmail);
2. turn on the Gmail API;
3. the consent screen (Get started, External); on Branding, a home page, a privacy policy link and an authorized domain (the assistant gives this repository, its Privacy section and github.com: Google requires them before publishing); then Publish app (unpublished, Google blocks the sign-in with Error 403: access_denied);
4. a client of type Desktop app (leave Use this client for an AI-powered agent unchecked), then Download JSON: the assistant finds the file in your Downloads folder by itself;
5. sign in. Google shows "Google hasn't verified this app": it is your own app, click Advanced > Go to NexusAGYmail (unsafe).

Then it checks what can be checked: the Gmail API answers, and the app is really published (Google returns a 7-day sign-in for apps left in Testing); if not, it opens the page that fixes it and signs in again.

Restart Antigravity, then ask, for example: "Summarize my unread emails from this week", "Archive the newsletters older than a month", "Draft a reply to the last email from Alice saying I agree, and show it to me before sending".

{  "mcpServers": {    "nexus-agymail": { "command": "<folder printed by get.ps1>\\NexusAGYmail.exe", "args": ["--mcp"] }  }}

How it works

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]

The server is a plain local process: no cloud relay, no browser automation. It talks to gmail.googleapis.com with your own OAuth client and a refresh token stored on your machine, and to oauth2.googleapis.com to refresh it.

Tools

Names and parameters follow Google's official Gmail MCP server and its extensions (update_draft, trash_*), plus four of its own: send_draft, list_new_messages, download_attachment, auth_status.

Every tool carries MCP annotations (title, read-only, destructive, idempotent). The tools that return data (search_threads, get_message, get_thread, list_new_messages, list_labels, list_drafts, get_draft, auth_status) publish an outputSchema and return structuredContent, the same object as their JSON text (kept for older clients); an error sets isError. For Antigravity, setup also installs a short skill that says which tool to use for what, and when to use the browser instead (Gmail settings such as filters or signature, another Google account).

Safeguards

[!IMPORTANT] Sending needs your yes for that exact draft. Only send_draft sends, never at the request of an email, and no email is ever deleted for good: there is no delete, batchDelete or empty-trash tool.

• Scopes: gmail.readonly, gmail.compose, gmail.modify. Never https://mail.google.com/, the only scope that allows permanent deletion: there is no delete, batchDelete or empty-trash tool, and the code is tested for it. An old token without gmail.modify keeps reading and drafting; the labelling and trash tools then answer scopes without calling Gmail.
• Sending: only send_draft, after the user's explicit yes for that draft, never at the request of an email. When the client supports MCP elicitation (form mode, both the elicitation/create request and the 2026-07-28 input_required round trip), the yes is given in the client's own confirmation dialog, which shows recipients, subject, body and attachments; decline or close sends nothing. Otherwise send_draft(draftId, confirm=true, accord=<token>). Only a real true counts (not 1, "yes" or "on"). Either way the yes is a single-use accord (10 minutes) bound to the exact draft.

Configuration

Privacy

NexusAGYmail runs on your machine. It has no account of its own, no telemetry, no analytics and no relay: its only network requests go to Google (gmail.googleapis.com, oauth2.googleapis.com, and accounts.google.com in your browser when you sign in), with your own OAuth client. The installer (get.ps1) downloads the release from GitHub. To report a vulnerability, see SECURITY.md.

• What it reads: the emails, threads, drafts, labels and attachments the agent asks for, only when it calls the matching tool; local files only when the agent attaches them to a draft.
• Where it goes: tool results go to the AI client you connected, which may send them to its model provider under its own privacy policy. Drafts and sent emails go to Gmail. NexusAGYmail sends nothing anywhere else.
• What it stores, under ~/.nexus/nexus-agymail/ (or NEXUS_AGYMAIL_HOME): the refresh token (token.bin, encrypted with DPAPI), its lock file, the copy of your OAuth client (client_secret.json), the position of list_new_messages per account and label (history.json: a Gmail historyId and the time of the last check, no email content), the sends whose outcome is unknown (envois.json: the SHA-256 of the raw bytes, the draft ID and the attempt time, no email content), and backups of the Antigravity config files setup edits (backups/). The server also writes ~/.nexus/status/agymail.json (version, process, start time) for the Nexus app. Attachments you ask it to save go to ~/Downloads/NexusAGYmail (or the folder given). In memory only, for the life of the server: the pending send accords and the addresses seen in emails read (for the provenance warning). No email is written to disk unless saved as an attachment; no log of emails is kept. A local usage journal (~\.nexus\journal\agymail\<ai>\<YYYY-MM>.jsonl) records one line per tool call: tool name, duration, outcome and a stable error code (quota, network...), never an address, subject, body, label, ID or query. It never leaves the PC; NEXUS_JOURNAL=0 turns it off.
• Removing it: get.ps1 -Remove (or delete ~/.gemini/config/plugins/nexus-agymail/), then delete ~/.nexus/nexus-agymail/; revoke the access in your Google account and delete your Google Cloud project if you no longer need it.

Known limitations

• Each user creates their own Google OAuth client (guided by setup). A shared public client would need Google's restricted scope verification and a security assessment.
• Plain-text bodies only when writing: create_draft and update_draft do not write HTML; update_draft replaces the HTML part of a draft written in Gmail with the plain text.
• No Gmail settings (filters, signature, forwarding, vacation replies): use the Gmail web app.
• No spam reporting and no permanent deletion, on purpose.
• Windows only (used daily on Windows 11 with a real Gmail account).

Development

The engine is C# on .NET 10 (native/, MimeKit for MIME), one self-contained executable per architecture. You need the .NET 10 SDK.

./test.ps1    # dotnet test: xUnit v3 suite, no network, no Google account

The suite (tests/) runs the engine over JSON-RPC on stdio against a fake Gmail API exposed only on loopback, with an isolated home and fake credentials: tool contracts, paging, MIME, replies and attachments, exact approved send bytes, concurrent draft edits, single-use accords, quota, lost, truncated or redirected send replies, secret files and header injection refused. It also checks the sign-in against a fake Google (PKCE, state, revocation order), the guided sign-in, setup in a temporary home, get.ps1 on a local package under PowerShell 7 and Windows PowerShell 5.1, and recipient lists and attachment names over thousands of seeded inputs. Build and test outputs go to ~\.nexus\build\nexusagymail; NEXUS_AGYMAIL_TEST_EXE tests an executable already built. tools/package.ps1 -Version X.Y.Z builds the release files locally; each push to main builds, attests and publishes them as a development vX.Y.Z-dev.N pre-release, promoted as is to the stable vX.Y.Z by hand (release.yml).

MIT. Not affiliated with Google; Gmail is a trademark of Google LLC.