/google-workspace-setup

name: google-workspace-setup
description: "Connect Google Workspace (Gmail, Calendar, Docs) for email-aware planning and meeting prep. Use when the user says 'connect Gmail/Google', 'hook up my work email'. Not for local macOS calendar speed only; use `calendar-setup`. Not for Microsoft; use `ms-teams-setup`."
integration:
  id: google-workspace
  name: Google Workspace
  auth: oauth2
  mcp_server: google-workspace-mcp
  category: communication
  sync_direction: bidirectional

Google Workspace Setup

Connect your Google Workspace to Dex so your daily plans, meeting prep, and weekly reviews get richer context from email, Google Calendar, and Docs.

What This Enables

Once connected, Dex can:

**Read:**

• Search emails by sender, subject, or keyword
• Surface unread emails from priority senders
• Pull email threads for meeting attendees
• Access Google Calendar events (if not using Apple Calendar)
• Search Google Docs and Sheets

**Write (always with your confirmation):**

• Send emails (Dex will always show you the draft and ask before sending)
• Create calendar events
• Create or update Google Docs

**Skill Enhancements:**

• **Daily Plan** (`/daily-plan`) gets an email digest -- unread count, threads needing reply, emails from today's meeting contacts
• **Meeting Prep** (`/meeting-prep`) shows recent email threads with each attendee
• **Week Review** (`/week-review`) includes email stats -- sent/received, response time, top correspondents
• **Draft Messages** (if configured) can send via Gmail with confirmation

**New Capabilities:**

• **Email Follow-Up Detection:** During `/daily-plan`, Dex checks for emails awaiting replies for more than 48 hours and surfaces them: "Sarah hasn't replied to your pricing email from 3 days ago. Draft a nudge?"

Privacy

Dex reads your email **on demand** -- nothing is stored permanently. Emails are fetched, summarized, and discarded after the session. Only YOUR account is accessible (scoped to your OAuth login). The OAuth token stays local on your machine and is gitignored.

When to Run

• User types `/google-workspace-setup`
• User asks about connecting Gmail or Google Workspace
• User wants email context in daily plans or meeting prep
• During `/integrate-mcp` if Gmail or Google Workspace is mentioned

---

Setup Flow

Step 1: Check if Already Connected

1. Check `System/integrations/config.yaml` for `google-workspace.enabled: true` 2. If enabled, try a test query via Google Workspace MCP (e.g., search for a recent email) 3. If healthy and responding, skip to **Step 5** (Configure Labels) 4. If the tool is not available or errors, continue to Step 2

Step 2: Explain What We're Setting Up

Say:

**Let's connect Google Workspace to Dex.**

This uses an open-source MCP bridge that connects to your Google account via OAuth.
You'll authorize Dex once, and it remembers your login locally.

**What you'll need:**
- A Google account (Gmail, Workspace, or personal)
- About 3 minutes for the OAuth flow

**What Dex will be able to do:**
- Read your emails (search, unread, threads)
- Read Google Calendar, Docs, and Sheets
- Send emails and create events (always with your confirmation first)

**Ready to go?**

Wait for confirmation.

Step 3: Add the Google Workspace MCP Server

Check the user's MCP configuration. If `google-workspace-mcp` is not listed:

1. Explain what we're adding:

I need to add the Google Workspace connector to your Dex configuration.

This is an open-source bridge (github.com/taylorwilsdon/google_workspace_mcp)
that connects to Google's APIs via OAuth. Your credentials stay on your machine.

2. Add to the user's `.mcp.json` (use the `/dex-add-mcp` skill or manual edit):

{
  "google-workspace-mcp": {
    "command": "npx",
    "args": ["-y", "google-workspace-mcp"],
    "env": {}
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 4: Authenticate via OAuth

1. Run `npx google-workspace-mcp` -- this starts the OAuth flow 2. A browser window opens for Google sign-in 3. The user authorizes the requested scopes (Gmail read/send, Calendar, Docs) 4. The token is saved locally to `System/.gmail-oauth-token.json`

**If OAuth succeeds:**

Connected! I can see your Google Workspace account.

**If it fails:**

The OAuth flow didn't complete. A few things to check:

1. **Did the browser open?** If not, try copying the URL from the terminal output
2. **Did you approve all permissions?** Dex needs Gmail, Calendar, and Docs access
3. **Firewall or proxy?** Corporate networks sometimes block OAuth redirects

Want to retry?

Retry up to 2 times, then offer to skip and come back later.

Step 5: Configure Labels and Write Preferences

Once connected, ask:

**Which Gmail labels matter most for your work?**

I'll prioritize these when building your email digest.

Common choices:
- INBOX (always included)
- IMPORTANT
- STARRED
- Custom labels (e.g., "Deals", "Follow-Up")

**Which labels should I watch?** (Just list names, or say "show me what's available")

Then ask about write operations:

**For sending emails and creating events:**

Would you prefer:
1. **Auto-draft** -- I'll compose messages and show them for your approval before sending
2. **Ask each time** -- I'll ask before even drafting anything

(You can change this anytime by re-running /google-workspace-setup)

Save their preference. Map choice 1 to `draft_and_send: true`, choice 2 to `draft_and_send: false`.

Step 6: Test the Connection

Run a quick test to confirm everything works:

1. Search for a recent email (e.g., from the last 24 hours) 2. Verify calendar access (list today's events)

Show a brief summary:

**Quick test results:**
- Email search: Working (found [N] recent emails)
- Calendar: Working (found [N] events today)

Everything looks good!

If either fails, troubleshoot before proceeding.

Step 7: Save Configuration

Write to `System/integrati