🌐 Antigravity Google Workspace Plugin

Unified Automation Bridge, Token-Optimized Telemetry & Dispatch Firewall for Google Workspace (Gmail · Drive · Docs · Sheets · Calendar · Tasks · Contacts)

📖 Why Google Workspace Plugin?

Most Google Workspace integrations force AI agents into one of two traps:

1. Tool Overload & Context Bloat: Splitting every Google service into a separate server wastes memory, burns LLM context with repetitive schemas, and dumps hundreds of emails into prompt memory.

2. Unchecked Destructive Authority: Giving an LLM unconstrained access to send live emails or delete Drive files leads to accidental outbounds and catastrophic data loss.

Antigravity Google Workspace Plugin solves both:

• 🌐 7-in-1 Unified Hub: A single, lightweight FastMCP engine connects Calendar, Tasks, Gmail, Drive, Docs, Sheets, and Contacts.

• 🛡️ The Dispatch Firewall: Read and draft operations execute instantly; high-risk actions (sending live emails, trashing Drive files, canceling meetings) require explicit user confirmation.

• ⚡ Token-Optimized Telemetry: Bounded list limits, smart search filtering (newer_than:2d, is:unread), and specific spreadsheet cell ranges prevent LLM context exhaustion.

• 🌅 Morning Executive Briefing: 1-shot situational routine combining calendar agenda, pending tasks, and unread priority emails into an actionable summary.

Related MCP server: google-services-mcp

🏛️ System Architecture

Deep Developer Documentation: For complete OAuth lifecycle flows, Dispatch Firewall state machines, token quarantine models, and API schemas, see docs/ARCHITECTURE.md.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       GOOGLE ANTIGRAVITY AGENT / MCP HOST                   │
│                    (Antigravity CLI · Claude Desktop · Cursor)              │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ JSON-RPC (stdio)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│              ANTIGRAVITY GOOGLE WORKSPACE PLUGIN (mcp/server.py)            │
├─────────────────────────────────────────────────────────────────────────────┤
│ 🛡️ Strict Dispatch Firewall (Pre-Execution 3-Point Confirmation)           │
│ 🔐 OAuth 2.0 Dynamic Token Engine (Auto-Refresh & Local Quarantine)        │
├──────────────────────────────────────┬──────────────────────────────────────┤
│ 📅 Google Calendar (Agenda/Events)   │ 📬 Gmail (Draft-First & Search)      │
│ ✅ Google Tasks (Action Items)       │ 📂 Google Drive (Scoped Retrieval)   │
│ 📝 Google Docs (Document Engine)     │ 📊 Google Sheets (Bounded A1 Ranges) │
│ 👥 Google Contacts (Address Book)    │ ⚡ Error Filtration & Sanitizer      │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ HTTPS (Google APIs v1/v3/v4)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        GOOGLE CLOUD PLATFORM / WORKSPACE                    │
│        [ Gmail · Drive · Docs · Sheets · Calendar · Tasks · Contacts ]      │
└─────────────────────────────────────────────────────────────────────────────┘

🛡️ The Dispatch Firewall: Operational Safety Guardrails

To safeguard your communications and data, operations are partitioned into two strict security tiers:

🛠️ Tool Catalog (22 Operations Across 7 Services)

🚀 Quickstart & Setup

1. Prerequisites & Google Cloud Setup

1. Create a Google Cloud Project in the Google Cloud Console.

2. Enable the following 7 APIs:

   • Google Calendar API

   • Google Tasks API

   • Gmail API

   • Google Drive API

   • Google Docs API

   • Google Sheets API

   • People API (Contacts)

3. Configure the OAuth Consent Screen (User Type: External, add your Google account as a Test User).

4. Create OAuth 2.0 Client IDs (Application Type: Desktop app).

5. Download the credentials JSON, rename it to credentials.json, and place it in the centralized credential vault:

   • Linux / macOS: ~/.gemini/credentials/google-workspace/credentials.json

   • Windows: %USERPROFILE%\.gemini\credentials\google-workspace\credentials.json (Alternatively, set GOOGLE_WORKSPACE_CREDENTIALS_PATH; legacy path ~/.gemini/config/google_workspace/ is supported as fallback).

2. Authentication Setup

Run the interactive local authenticator:

pip install -r mcp/requirements.txt
python mcp/auth_setup.py

A browser window will open automatically asking you to authorize your Google account. Upon approval, token.json is generated locally and cached for automated token refresh.

# Check token health and expiry without starting a server:
python mcp/auth_setup.py --check

# Force a clean re-authentication flow:
python mcp/auth_setup.py --force

🔑 Permanent Tokens: How to Bypass the 7-Day Expiration

By default, Google puts all new Google Cloud projects in "Testing" mode. Under Google's security policy, refresh tokens in "Testing" mode strictly expire after 7 days (168 hours), forcing you to re-authenticate every week.

How to Make Your Refresh Token Permanent (Never Expires):

1. Open the Google Cloud Console - OAuth Consent Screen.

2. Under Publishing status, click the button: "PUBLISH APP" and confirm.

3. Your app's status will change from Testing to In Production.

4. Do you need Google verification? NO!

   • For your own personal Google account, you do not need public verification.

   • When authenticating, Google will show a screen saying "Google hasn't verified this app".

   • Click Advanced ➔ Go to (unsafe) and click Continue.

5. Once authorized, Google issues a permanent refresh token that does not expire after 7 days. You will never have to re-authenticate weekly again!

⚙️ Client Configurations

Pathway A: Google Antigravity Plugin (Recommended)

1. Clone or copy into your local Antigravity plugins directory:

   git clone https://github.com/karansinghverma979/antigravity-google-workspace-plugin.git ~/.gemini/config/plugins/google-workspace-plugin

2. Add to your Antigravity mcp_config.json:

   {
     "mcpServers": {
       "google-workspace-mcp": {
         "command": "python",
         "args": [
           "C:\\Users\\<YourUsername>\\.gemini\\config\\plugins\\google-workspace-plugin\\mcp\\server.py"
         ],
         "disabled": false
       }
     }
   }

3. Antigravity automatically loads plugin.json, activates the google-workspace skill (skills/google-workspace/SKILL.md), and registers the agent (agents/google_workspace.md).

Pathway B: Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "google-workspace": {
      "command": "python",
      "args": [
        "/path/to/antigravity-google-workspace-plugin/mcp/server.py"
      ]
    }
  }
}

🔒 Security & Privacy Standard

• Sovereign External Quarantine: Credentials (credentials.json) and active OAuth tokens (token.json) reside strictly outside the repository tree in the centralized vault at ~/.gemini/credentials/google-workspace/ (with legacy fallback to ~/.gemini/config/google_workspace/). The git repository tree contains zero sensitive artifacts and survives complete repo wipes (git clean -fdx).

• Dynamic Path Expansion: Dynamically expands paths using os.path.expanduser with full support for GOOGLE_WORKSPACE_TOKEN_PATH and GOOGLE_WORKSPACE_CREDENTIALS_PATH environment variables, avoiding machine-specific paths.

• Git Defense-in-Depth: .gitignore strictly blocks all token.json, credentials.json, *.token, *.pem, *.key, and .env files. A sanitized credentials.json.example is committed for reference.

• OpenSSF CI Hardening: GitHub Actions workflows enforce permissions: contents: read and pin dependencies to immutable 40-character commit SHAs.

• Vulnerability Disclosure: Managed through coordinated disclosure in SECURITY.md.

Maintained by Karan Singh Verma · Released under the MIT License