Google Workspace API 开发指南：Gmail、Calendar、Drive、Sheets 等完整集成教程

google-workspace by jezweb/claude-skills

428 周安装量

650 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jezweb/claude-skills --skill google-workspace

自动化云服务 API

🇨🇳中文介绍

Google Workspace APIs

状态 : 生产就绪 最后更新 : 2026-01-09 依赖项 : Cloudflare Workers (推荐), Google Cloud Project 技能版本 : 1.0.0

快速参考

API	常见用例	参考文档
Gmail	邮件自动化，收件箱管理	gmail-api.md
Calendar	事件管理，日程安排	calendar-api.md
Drive	文件存储，共享	drive-api.md
Sheets	电子表格数据，报告	sheets-api.md

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

共享的身份验证模式

所有 Google Workspace API 都使用相同的身份验证机制。请根据您的用例选择。

选项 1: OAuth 2.0 (用户上下文)

最适合：代表用户操作，访问用户特定数据。

// 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()
}

始终为刷新令牌请求 access_type=offline
使用 prompt=consent 以确保返回刷新令牌
安全存储刷新令牌（Cloudflare KV 或 D1）
访问令牌约 1 小时后过期

选项 2: 服务账号 (服务器到服务器)

最适合：后端自动化，无需用户交互，全域委派。

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
}

全域委派 (模拟用户)：

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,
})

在 Google Cloud Console 中创建服务账号
下载 JSON 密钥文件
在管理控制台中启用全域委派（如果需要模拟用户）
将密钥存储为 Cloudflare 密钥（JSON 字符串化）

所有 Google Workspace API 都强制执行配额。这些是近似值 - 请检查每个 API 的具体限制。

每用户限制 (OAuth)

API	读取	写入	备注
Gmail	250/用户/秒	250/用户/秒	所有方法的总和
Calendar	500/用户/100秒	500/用户/100秒	每个日历
Drive	1000/用户/100秒	1000/用户/100秒
Sheets	100/用户/100秒	100/用户/100秒	低于其他 API

API	每日配额	每分钟	备注
Gmail	10亿单位	可变	基于单位（发送 = 100 单位）
Calendar	100万次查询	500/秒
Drive	10亿次查询	1000/秒
Sheets	无限制	500/用户/100秒

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')
}

大多数 Google API 支持将多个请求批处理为一个 HTTP 调用。

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())
}

每批最多 100 个请求（大多数 API）
每批最多 1000 个请求（某些 API，如 Drive）
批处理中的每个请求都计入配额

Cloudflare Workers 配置

// 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" }
  ]
}

需要设置的密钥：

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_ACCOUNT

错误：刷新令牌时出现 "invalid_grant"

原因 : 刷新令牌已被撤销或过期（6 个月不活动） 解决方法 : 重新验证用户，请求新的刷新令牌

错误：OAuth 时出现 "access_denied"

原因 : 应用未验证，或用户不在测试用户列表中 解决方法 : 将用户添加到 OAuth 同意屏幕的测试用户，或完成应用验证

错误："insufficientPermissions" (403)

原因 : 缺少所需的范围 解决方法 : 检查授权 URL 中的范围，使用正确的范围重新验证

错误："rateLimitExceeded" (403)

原因 : 配额已超出 解决方法 : 实现指数退避，降低请求频率，请求增加配额

错误：已知资源上出现 "notFound" (404)

原因 : 使用了错误的 API 版本，或资源在回收站中 解决方法 : 检查 URL 中的 API 版本，检查回收站中的已删除项目

每个 API 的详细模式都在 references/ 目录中。在使用特定 API 时加载这些文档。

消息的增删改查，标签，会话
MIME 处理，附件
推送通知 (Pub/Sub)

事件的增删改查，重复事件
空闲/忙碌查询
日历共享

文件上传/下载
权限，共享
搜索查询

读取/写入单元格
A1 表示法，范围
批量更新

机器人，Webhooks
Cards v2，交互式表单
空间，成员，反应

(随着 MCP 服务器的构建，将添加其他 API 参考)

包版本 (已验证于 2026-01-09)

{
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20260109.0",
    "wrangler": "^4.58.0",
    "jose": "^6.1.3"
  }
}

随着 MCP 服务器的构建，将记录以下 API：

Gmail API
Calendar API
Drive API
Sheets API
Docs API
Chat API (从 google-chat-api 技能迁移而来)
Meet API
Forms API
Tasks API
Admin SDK
People API

🇺🇸English

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.

// 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 access_type=offline for refresh tokens
Use prompt=consent to ensure refresh token is returned
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.

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

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

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.

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

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

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_ACCOUNT

Common 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 references/ directory. Load these when working with specific APIs.

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)

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

Weekly Installs

428

Repository

jezweb/claude-skills

GitHub Stars

650

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code338

gemini-cli287

opencode286

codex252

antigravity241

cursor238

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

66,100 周安装

Google Workspace API 开发指南：Gmail、Calendar、Drive、Sheets 等完整集成教程

🇨🇳中文介绍

Google Workspace APIs

快速参考

相关 Skills

共享的身份验证模式

选项 1: OAuth 2.0 (用户上下文)

选项 2: 服务账号 (服务器到服务器)

通用速率限制

每用户限制 (OAuth)

每项目限制

处理速率限制

批量请求

Cloudflare Workers 配置

常见错误

错误：刷新令牌时出现 "invalid_grant"

错误：OAuth 时出现 "access_denied"

错误："insufficientPermissions" (403)

错误："rateLimitExceeded" (403)

错误：已知资源上出现 "notFound" (404)

API 特定指南

Gmail API

Calendar API

Drive API

Sheets API

Chat API

包版本 (已验证于 2026-01-09)

官方文档

技能路线图

🇺🇸English

Google Workspace APIs

Quick Reference

Shared Authentication Patterns

Option 1: OAuth 2.0 (User Context)

Option 2: Service Account (Server-to-Server)

Common Rate Limits

Per-User Limits (OAuth)

Per-Project Limits

Handling Rate Limits

Batch Requests

Cloudflare Workers Configuration

Common Errors

Error: "invalid_grant" on Token Refresh

Error: "access_denied" on OAuth

Error: "insufficientPermissions" (403)

Error: "rateLimitExceeded" (403)

Error: "notFound" (404) on Known Resource

API-Specific Guides

Gmail API

Calendar API

Drive API

Sheets API

Chat API

Package Versions (Verified 2026-01-09)

Official Documentation

Skill Roadmap

最新 Skills