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
---

<!-- Generated from `.claude/skills/google-workspace-setup/SKILL.md` by `scripts/generate-agents-skills.py`. Do not edit. -->

# 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 accounts you explicitly connect are accessible. OAuth credentials stay local in `~/.google-mcp/credentials.json`, and account tokens stay local under `~/.google-mcp/tokens/`; never paste either into chat or commit them to Git.

**Permission truth:** this connector requests a fixed set of nine OAuth scopes covering Docs, Drive, Sheets, Gmail, Calendar, Slides, and Forms. Changing selections on Google's consent screen does not narrow the permissions the connector requests. Its `--read-only` server mode blocks write tools after authorization, but does not reduce the underlying OAuth grant. Explain this before setup and let the user stop if that access is broader than they want.

## 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

Do not treat `System/integrations/config.yaml` as the only connectedness signal. Google Workspace email may already be usable through a **Gmail session connector** already available in this session, even when that file does not say `google-workspace.enabled: true`.

1. **Session connectors already available.** Inspect the tools already present in this session for Gmail, Google Calendar, and Google Drive.
   - A **Calendar-only** or **Drive-only** connector is not a full Google Workspace connection. Do not skip setup in those cases — this skill's job includes email, and those connectors do not provide Gmail.
   - If a **Gmail** session connector is available, try a test query (search a recent email) **without** requiring Dex config to be enabled first. If Gmail responds, treat email as already connected: do not add a second MCP server, and skip to **Step 6** (Configure Labels). Note missing Calendar or Drive tools, but do not install a duplicate Gmail server when Gmail already works.
2. **Dex config.** Check `System/integrations/config.yaml` for `google-workspace.enabled: true`. If enabled, try a **Gmail** test query via `google-workspace-mcp` (search a recent email). Calendar or Drive responding is not enough to skip. If Gmail responds, skip to **Step 6**. If Gmail fails, continue to Step 2 even when Calendar looks healthy — do not bypass re-auth.
3. If Gmail is not healthy on either path, 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)
- Node.js 20 or newer
- Access to create an OAuth client in Google Cloud
- About 15-20 minutes for the one-time Google Cloud and OAuth setup

**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)

**Important permission detail:**
The connector requests a fixed set of nine OAuth scopes across Docs, Drive, Sheets,
Gmail, Calendar, Slides, and Forms. Choosing fewer items on Google's consent screen
does not narrow the permissions the connector requests. If that is broader than you
want, stop here rather than authorizing it.

**Ready to go?**
```

Wait for confirmation.

### Step 3: Create the Google Cloud App

The installed connector is the npm package `google-workspace-mcp`, maintained at
`github.com/pm990320/google-workspace-mcp`. Keep every setup and troubleshooting
instruction aligned to that package and its CLI.

Walk the user through the following browser steps. This is the substantial part of setup:

1. **Create or select a Google Cloud project.**
2. **Enable the required Google APIs:** Google Docs, Drive, Sheets, Gmail, Calendar,
   Slides, and Forms.
3. **Configure the OAuth consent screen.** Use the audience appropriate to the user's
   account or organization. If the app is in testing mode, continue to the next step.
4. **Add the Google account as a test user** when the consent screen is in testing mode.
5. Create a **Desktop app** OAuth client. Download its JSON credentials file.
6. Put that file at `~/.google-mcp/credentials.json`. Create `~/.google-mcp/` first if
   needed and restrict the file to the current user. Ask for the downloaded file's local
   path; never ask the user to paste its contents into chat.

Confirm that the credentials file exists before continuing, but never print or read its
secret values into the conversation.

### Step 4: Add the Google Workspace MCP Server

If Step 1 already found a healthy **Gmail** session connector, skip this step — do not register a second Gmail/Workspace server. A healthy Calendar or Drive connector alone is not a reason to skip.

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/pm990320/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):

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

The config key, the `npx` package, and the name in the explanation must all be `google-workspace-mcp`. Do not substitute a different repository or package name.

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

### Step 5: Authenticate via OAuth

1. Run `npx -y google-workspace-mcp setup` to verify the local credentials file.
2. Run `npx -y google-workspace-mcp accounts add main` to start the OAuth flow.
3. A browser window opens for Google sign-in. If it does not, use the authorization URL
   printed by the connector.
4. The user reviews and authorizes the connector's fixed permission set.
5. The account token is saved locally under `~/.google-mcp/tokens/`.
6. Run `npx -y google-workspace-mcp status` and require a ready result before continuing.

**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. Do not mark the integration
enabled unless the status command and the live tool checks both succeed.

### Step 6: 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 7: Test the Connection

Run a quick test to confirm everything works. **Email is the connectedness bar.** Calendar is extra.

1. **Email (required).** Search for a recent email (e.g., from the last 24 hours). If this fails, troubleshoot before proceeding — do not write `google-workspace.enabled: true` until Gmail responds.
2. **Calendar (optional).** If a Calendar connector is available, list today's events. If Calendar is missing — including a Gmail-only session connector — note it and continue. Do not block saving config on a missing calendar.

Show a brief summary:

```
**Quick test results:**
- Email search: Working (found [N] recent emails)
- Calendar: Working (found [N] events today)
  # or: Not available in this session — email still counts as connected
```

If email works, proceed to Step 8 even when Calendar is missing. Only email failure blocks saving configuration.

### Step 8: Save Configuration

Write to `System/integrations/config.yaml` -- update the google-workspace section:

```yaml
google-workspace:
  enabled: true
  configured_at: YYYY-MM-DD
  mcp_server: google-workspace-mcp
  auth_type: oauth2
  account: user@example.com
  labels:
    - INBOX
    - IMPORTANT
  features:
    email_digest: true
    email_followup: true
    draft_and_send: true   # or false based on user preference
```

If the file already exists, only update the `google-workspace:` section. Preserve other integration configs.

Read and write `calendar.provider` in `System/user-profile.yaml`, not in `System/integrations/config.yaml`.

If `calendar.provider` is already `apple`, leave it — Apple Calendar remains the calendar source.

If `calendar.provider` is missing and `work_calendar` is set, leave it — that is still Apple Calendar.

If `calendar.provider` is `none`, or the field is missing and no `work_calendar` is set, set `provider: google` only when Google Calendar is actually available in this session.
That means `google-workspace-mcp` is registered, or a Google Calendar session connector is present.
A Gmail-only connection must not change the calendar source.

When those conditions hold, write this in `System/user-profile.yaml`:

```yaml
calendar:
  provider: google
```

Keep any existing `work_calendar` value. Do not invent new privacy or consent language; this only records which calendar daily planning should read.

### Step 9: Confirm with Capability Cascade

```
**Google Workspace is connected!**

Here's what just got enhanced:

- **Daily Plan** (`/daily-plan`) now includes an email digest:
  - Unread count from priority senders
  - Threads needing reply (> 24h)
  - Emails from today's meeting attendees
  - Follow-up detection ("Sarah hasn't replied in 3 days")

- **Meeting Prep** (`/meeting-prep`) now shows email context:
  - Recent email threads with each attendee
  - Last email date and topic
  - Unanswered emails to flag

- **Week Review** (`/week-review`) now includes email stats:
  - Emails sent/received this week
  - Average response time
  - Top senders and recipients

You can adjust settings anytime by running `/google-workspace-setup` again.
```

---

## New Capabilities

### Email Follow-Up Detection

During `/daily-plan`, Dex checks for stale email threads:

1. Search for sent emails from the last 7 days
2. For each sent email, check if there's a reply
3. If no reply after 48 hours, surface it:

```
**Emails awaiting reply:**
- Sarah Chen hasn't replied to your pricing email (sent 3 days ago). Draft a nudge?
- Mike Ross hasn't replied to the proposal follow-up (sent 2 days ago).
```

**Rules:**
- Only check emails YOU sent (not inbound)
- 48-hour threshold (skip weekends in the count)
- Limit to 5 items max (don't overwhelm)
- Only runs if `google-workspace.features.email_followup: true` in config
- Surfaces during the email digest step of `/daily-plan`

---

## Troubleshooting

### OAuth Token Expired

Google OAuth tokens typically last 1 hour, but refresh tokens are longer-lived. If you see auth errors:

1. Run `npx -y google-workspace-mcp status` to identify the affected account.
2. If re-authorization is required, remove and re-add that named account through the
   connector's account commands, then complete the browser flow again.
3. Re-run the live email and calendar checks before marking the setup healthy.

### "Google Workspace MCP not found"

First check whether a **Gmail** session connector is already available in this session. If Gmail is healthy, Dex can use it and does not need a second server. A Calendar-only or Drive-only connector is not enough — continue and add `google-workspace-mcp` so email works. If Gmail is missing or unhealthy, re-run `/google-workspace-setup` and it will detect and add `google-workspace-mcp`.

### Permission Errors

If certain features don't work (e.g., can't send emails):

1. Run `npx -y google-workspace-mcp accounts test-permissions main` (replace `main` if
   the user chose another account name).
2. Confirm that all seven required Google APIs are enabled in the selected Cloud project.
3. Confirm that the account is an allowed test user when the consent screen is in testing.
4. Do not tell the user to narrow or expand individual scopes: this connector requests a
   fixed set, so the remedy is to fix the project/API/test-user setup or stop using it.

### Rate Limiting

Google APIs have generous limits for personal use. If you see rate errors:

1. Wait 60 seconds and retry
2. If persistent, you may be hitting a Workspace admin quota
3. Contact your IT team if you're on a managed Workspace account

### Corporate Workspace Restrictions

Some organizations restrict OAuth access for third-party apps:

1. Check with your IT admin if OAuth is allowed
2. They may need to whitelist the google-workspace-mcp client ID
3. Alternative: Use a personal Gmail account for now

---

## Reconfiguration

If the user runs `/google-workspace-setup` when already configured:

1. Check current status via a test query — including a Gmail session connector already available in this session, not only `System/integrations/config.yaml`. Calendar-only or Drive-only is not enough to treat Gmail as connected.
2. Show current config from `System/integrations/config.yaml` if present
3. Offer options:
   - Update watched labels
   - Change write preferences (auto-draft vs ask each time)
   - Re-authenticate (if token expired)
   - Disconnect Gmail

### Disconnect Flow

If user wants to disconnect:

1. Update `System/integrations/config.yaml`:
   ```yaml
   google-workspace:
     enabled: false
   ```
2. Confirm: "Google Workspace is disconnected. Your daily plans, meeting prep, and reviews will no longer include email context. Run `/google-workspace-setup` anytime to reconnect."