/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). Keep Gmail draft ids consistent — see **Gmail draft identity** below.
• 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** after rewriting any raw `npx` `serve` entry to the session wrapper in Step 4. 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, Calen