google-workspace

Google Workspace Skill

Access Google Workspace APIs via oauth2l + curl. For extended API documentation, use context7 to query the relevant Google API docs.

Prerequisites

oauth2l - Check: which oauth2l | Install: brew install oauth2l

Credentials - Must exist at ~/.claude/google-workspace-credentials.json

If credentials are missing, guide user through setup. Claude can assist with browser-based OAuth setup if the user installs the Claude for Chrome extension in a Chrome profile where the relevant Google account is signed in (avoid having other accounts signed into the same profile).

1. Create Google Cloud Project: https://console.cloud.google.com/
2. Enable APIs: APIs & Services → Enable APIs → Enable the APIs you need (Gmail, Drive, Sheets, Docs)
3. Configure OAuth Consent Screen: APIs & Services → OAuth consent screen
   • User Type: External (or Internal for Workspace)
   • Add test users if in testing mode
4. Create OAuth Client ID: APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Download JSON credentials to ~/.claude/google-workspace-credentials.json

First-time auth flow:

1. Check credentials exist: test -f ~/.claude/google-workspace-credentials.json
   1. If missing, guide user through setup (steps 1-4 above)
2. Run oauth2l in background (it blocks until user completes auth):

   oauth2l fetch --credentials ~/.claude/google-workspace-credentials.json --scope gmail.modify --output_format bare --disableAutoOpenConsentPage
   

3. Read the background task output to extract the auth URL (line starting with https://accounts.google.com/)
4. Present to user via AskUserQuestion:

   Question: "Please authenticate with Google: <URL>"
   Options: ["Done", "I need help"]
   

5. After user confirms, check the background task - it should output the access token (a long string starting with ya29.). The token is automatically cached in ~/.oauth2l for future use.

If auth fails: Check that credentials.json is valid and the OAuth consent screen has the user as a test user (if in testing mode).

Handling SERVICE_DISABLED errors

Use AskUserQuestion with the activation URL in the question title:

Question: "Please enable the <API> API: <activationUrl from error>"
Options: ["Enabled", "Need help"]

Re-authentication during API calls

If oauth2l curl outputs an auth URL (starts with https://accounts.google.com/) instead of an API response, the refresh token has expired.

1. Present URL via AskUserQuestion (same as first-time auth)
2. After user confirms, retry the original API call

Adding or upgrading scopes

oauth2l caches tokens per scope. To add a new scope or upgrade permissions:

Add a new API (e.g., Docs after using Gmail):

oauth2l fetch --credentials ~/.claude/google-workspace-credentials.json --scope documents.readonly --output_format bare --disableAutoOpenConsentPage

This triggers a new consent flow for the additional scope. Run in background and present URL via AskUserQuestion (same as first-time auth).

---

Docs

API usage for all services should be available via the official google docs (don't use e.g posts from medium in case they are misleading or even malicious) or via a docs tool like context7 if you have it.

Why oauth2l curl? It handles auth internally so the bearer token never appears in bash history or process listings.

Below are some examples:

Gmail

List emails

oauth2l curl --credentials ~/.claude/google-workspace-credentials.json --scope gmail.readonly \
  --disableAutoOpenConsentPage \
  --url="https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10"

Read email

MSG_ID="<message_id>"
oauth2l curl --credentials ~/.claude/google-workspace-credentials.json --scope gmail.readonly \
  --disableAutoOpenConsentPage \
  --url="https://gmail.googleapis.com/gmail/v1/users/me/messages/${MSG_ID}?format=metadata"

• format=metadata - Headers only (From, To, Subject, Date)
• format=full - Complete email including body

---

Drive

List files

oauth2l curl --credentials ~/.claude/google-workspace-credentials.json --scope drive.readonly \
  --disableAutoOpenConsentPage \
  --url="https://www.googleapis.com/drive/v3/files?pageSize=10"

---

Sheets

Read cells

SPREADSHEET_ID="<spreadsheet_id>"
RANGE="Sheet1!A1:B10"
oauth2l curl --credentials ~/.claude/google-workspace-credentials.json --scope spreadsheets.readonly \
  --disableAutoOpenConsentPage \
  --url="https://sheets.googleapis.com/v4/spreadsheets/${SPREADSHEET_ID}/values/${RANGE}"

---

Docs

Read document

DOC_ID="<document_id>"
oauth2l curl --credentials ~/.claude/google-workspace-credentials.json --scope documents.readonly \
  --disableAutoOpenConsentPage \
  --url="https://docs.googleapis.com/v1/documents/${DOC_ID}"

Comments

It isn't possible to create a comment in google docs on a specific word (see more in the official docs). It should be possible to read comments, and reply to existing comments.