google-workspace
Original:🇺🇸 English
Translated
1 scripts
Build integrations with Google Workspace APIs (Gmail, Calendar, Drive, Sheets, Docs, Chat, Meet, Forms, Tasks, Admin SDK). Covers OAuth 2.0, service accounts, rate limits, batch operations, and Cloudflare Workers patterns. Use when building MCP servers, automation tools, or integrations with any Google Workspace API, or troubleshooting OAuth errors, rate limit 429 errors, scope issues, or API-specific gotchas.
1installs
Sourcejezweb/claude-skills
Added on
NPX Install
npx skill4agent add jezweb/claude-skills google-workspaceTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Google Workspace APIs
Status: Production Ready
Last Updated: 2026-01-09
Dependencies: Cloudflare Workers (recommended), Google Cloud Project
Skill Version: 1.0.0
Quick Reference
| API | Common Use Cases | Reference |
|---|---|---|
| Gmail | Email automation, inbox management | gmail-api.md |
| Calendar | Event management, scheduling | calendar-api.md |
| Drive | File storage, sharing | drive-api.md |
| Sheets | Spreadsheet data, reporting | sheets-api.md |
| Docs | Document generation | docs-api.md |
| Chat | Bots, webhooks, spaces | chat-api.md |
| Meet | Video conferencing | meet-api.md |
| Forms | Form responses, creation | forms-api.md |
| Tasks | Task management | tasks-api.md |
| Admin SDK | User/group management | admin-sdk.md |
| People | Contacts management | people-api.md |
Shared Authentication Patterns
All Google Workspace APIs use the same authentication mechanisms. Choose based on your use case.
Option 1: OAuth 2.0 (User Context)
Best for: Acting on behalf of a user, accessing user-specific data.
typescript
// Authorization URL
const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth')
authUrl.searchParams.set('client_id', env.GOOGLE_CLIENT_ID)
authUrl.searchParams.set('redirect_uri', `${env.BASE_URL}/callback`)
authUrl.searchParams.set('response_type', 'code')
authUrl.searchParams.set('scope', SCOPES.join(' '))
authUrl.searchParams.set('access_type', 'offline') // For refresh tokens
authUrl.searchParams.set('prompt', 'consent') // Force consent for refresh token
// Token exchange
async function exchangeCode(code: string): Promise<TokenResponse> {
const response = await fetch('https://oauth2.googleapis.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
code,
client_id: env.GOOGLE_CLIENT_ID,
client_secret: env.GOOGLE_CLIENT_SECRET,
redirect_uri: `${env.BASE_URL}/callback`,
grant_type: 'authorization_code',
}),
})
return response.json()
}
// Refresh token
async function refreshToken(refresh_token: string): Promise<TokenResponse> {
const response = await fetch('https://oauth2.googleapis.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
refresh_token,
client_id: env.GOOGLE_CLIENT_ID,
client_secret: env.GOOGLE_CLIENT_SECRET,
grant_type: 'refresh_token',
}),
})
return response.json()
}Critical:
- Always request for refresh tokens
access_type=offline - Use to ensure refresh token is returned
prompt=consent - Store refresh tokens securely (Cloudflare KV or D1)
- Access tokens expire in ~1 hour
Option 2: Service Account (Server-to-Server)
Best for: Backend automation, no user interaction, domain-wide delegation.
typescript
import { SignJWT } from 'jose'
async function getServiceAccountToken(
serviceAccount: ServiceAccountKey,
scopes: string[]
): Promise<string> {
const now = Math.floor(Date.now() / 1000)
// Create JWT
const jwt = await new SignJWT({
iss: serviceAccount.client_email,
scope: scopes.join(' '),
aud: 'https://oauth2.googleapis.com/token',
iat: now,
exp: now + 3600,
})
.setProtectedHeader({ alg: 'RS256', typ: 'JWT' })
.sign(await importPKCS8(serviceAccount.private_key, 'RS256'))
// Exchange JWT for access token
const response = await fetch('https://oauth2.googleapis.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: jwt,
}),
})
const data = await response.json()
return data.access_token
}Domain-Wide Delegation (impersonate users):
typescript
const jwt = await new SignJWT({
iss: serviceAccount.client_email,
sub: 'user@domain.com', // User to impersonate
scope: scopes.join(' '),
aud: 'https://oauth2.googleapis.com/token',
iat: now,
exp: now + 3600,
})Setup Required:
- Create service account in Google Cloud Console
- Download JSON key file
- Enable domain-wide delegation in Admin Console (if impersonating)
- Store key as Cloudflare secret (JSON stringified)
Common Rate Limits
All Google Workspace APIs enforce quotas. These are approximate - check each API's specific limits.
Per-User Limits (OAuth)
| API | Reads | Writes | Notes |
|---|---|---|---|
| Gmail | 250/user/sec | 250/user/sec | Aggregate across all methods |
| Calendar | 500/user/100sec | 500/user/100sec | Per calendar |
| Drive | 1000/user/100sec | 1000/user/100sec | |
| Sheets | 100/user/100sec | 100/user/100sec | Lower than others |
Per-Project Limits
| API | Daily Quota | Per-Minute | Notes |
|---|---|---|---|
| Gmail | 1B units | Varies | Unit-based (send = 100 units) |
| Calendar | 1M queries | 500/sec | |
| Drive | 1B queries | 1000/sec | |
| Sheets | Unlimited | 500/user/100sec |
Handling Rate Limits
typescript
async function withRetry<T>(
fn: () => Promise<T>,
maxRetries = 5
): Promise<T> {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn()
} catch (error: any) {
const status = error.status || error.code
if (status === 429 || status === 503) {
// Rate limited or service unavailable
const retryAfter = error.headers?.get('Retry-After') || Math.pow(2, i)
await new Promise(r => setTimeout(r, retryAfter * 1000))
continue
}
if (status === 403 && error.message?.includes('rateLimitExceeded')) {
// Quota exceeded - exponential backoff
await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000))
continue
}
throw error
}
}
throw new Error('Max retries exceeded')
}Batch Requests
Most Google APIs support batching multiple requests into one HTTP call.
typescript
async function batchRequest(
accessToken: string,
requests: BatchRequestItem[]
): Promise<BatchResponse[]> {
const boundary = 'batch_boundary'
let body = ''
requests.forEach((req, i) => {
body += `--${boundary}\r\n`
body += 'Content-Type: application/http\r\n'
body += `Content-ID: <item${i}>\r\n\r\n`
body += `${req.method} ${req.path} HTTP/1.1\r\n`
body += 'Content-Type: application/json\r\n\r\n'
if (req.body) body += JSON.stringify(req.body)
body += '\r\n'
})
body += `--${boundary}--`
const response = await fetch('https://www.googleapis.com/batch/v1', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': `multipart/mixed; boundary=${boundary}`,
},
body,
})
// Parse multipart response...
return parseBatchResponse(await response.text())
}Limits:
- Max 100 requests per batch (most APIs)
- Max 1000 requests per batch (some APIs like Drive)
- Each request in batch counts toward quota
Cloudflare Workers Configuration
jsonc
// wrangler.jsonc
{
"name": "google-workspace-mcp",
"main": "src/index.ts",
"compatibility_date": "2026-01-03",
"compatibility_flags": ["nodejs_compat"],
// Store OAuth tokens
"kv_namespaces": [
{ "binding": "TOKENS", "id": "xxx" }
],
// Or use D1 for structured storage
"d1_databases": [
{ "binding": "DB", "database_name": "workspace-mcp", "database_id": "xxx" }
]
}Secrets to set:
bash
echo "your-client-id" | npx wrangler secret put GOOGLE_CLIENT_ID
echo "your-client-secret" | npx wrangler secret put GOOGLE_CLIENT_SECRET
# For service accounts:
cat service-account.json | npx wrangler secret put GOOGLE_SERVICE_ACCOUNTCommon Errors
Error: "invalid_grant" on Token Refresh
Cause: Refresh token revoked or expired (6 months of inactivity)
Fix: Re-authenticate user, request new refresh token
Error: "access_denied" on OAuth
Cause: App not verified, or user not in test users list
Fix: Add user to OAuth consent screen test users, or complete app verification
Error: "insufficientPermissions" (403)
Cause: Missing required scope
Fix: Check scopes in authorization URL, re-authenticate with correct scopes
Error: "rateLimitExceeded" (403)
Cause: Quota exceeded
Fix: Implement exponential backoff, reduce request frequency, request quota increase
Error: "notFound" (404) on Known Resource
Cause: Using wrong API version, or resource in trash
Fix: Check API version in URL, check trash for deleted items
API-Specific Guides
Detailed patterns for each API are in the directory. Load these when working with specific APIs.
references/Gmail API
See references/gmail-api.md
- Message CRUD, labels, threads
- MIME handling, attachments
- Push notifications (Pub/Sub)
Calendar API
See references/calendar-api.md
- Events CRUD, recurring events
- Free/busy queries
- Calendar sharing
Drive API
See references/drive-api.md
- File upload/download
- Permissions, sharing
- Search queries
Sheets API
See references/sheets-api.md
- Reading/writing cells
- A1 notation, ranges
- Batch updates
Chat API
See references/chat-api.md
- Bots, webhooks
- Cards v2, interactive forms
- Spaces, members, reactions
(Additional API references added as MCP servers are built)
Package Versions (Verified 2026-01-09)
json
{
"devDependencies": {
"@cloudflare/workers-types": "^4.20260109.0",
"wrangler": "^4.58.0",
"jose": "^6.1.3"
}
}Official Documentation
- Google Workspace APIs: https://developers.google.com/workspace
- OAuth 2.0: https://developers.google.com/identity/protocols/oauth2
- Service Accounts: https://cloud.google.com/iam/docs/service-accounts
- API Explorer: https://developers.google.com/apis-explorer
- Quotas Dashboard: https://console.cloud.google.com/iam-admin/quotas
Skill Roadmap
APIs documented as MCP servers are built:
- Gmail API
- Calendar API
- Drive API
- Sheets API
- Docs API
- Chat API (migrated from google-chat-api skill)
- Meet API
- Forms API
- Tasks API
- Admin SDK
- People API