google-workspace

Google Workspace API

ステータス：本番環境で利用可能 最終更新日：2026-01-09 依存関係：Cloudflare Workers（推奨）、Google Cloud プロジェクト スキルバージョン：1.0.0

---

クイックリファレンス

API	一般的なユースケース	リファレンス
Gmail	メールの自動化、受信トレイの管理	gmail-api.md
Calendar	イベントの管理、スケジュール調整	calendar-api.md
Drive	ファイルの保存、共有	drive-api.md
Sheets	スプレッドシートのデータ、レポート作成	sheets-api.md
Docs	ドキュメントの生成	docs-api.md
Chat	ボット、Webhook、スペース	chat-api.md
Meet	ビデオ会議	meet-api.md
Forms	フォームの回答、作成	forms-api.md
Tasks	タスク管理	tasks-api.md
Admin SDK	ユーザー／グループ管理	admin-sdk.md
People	連絡先の管理	people-api.md

---

共通の認証パターン

すべての 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: '[email protected]',  // User to impersonate
  scope: scopes.join(' '),
  aud: 'https://oauth2.googleapis.com/token',
  iat: now,
  exp: now + 3600,
})

必要な設定：

1. Google Cloud Console でサービスアカウントを作成します
2. JSON キーファイルをダウンロードします
3. （なりすましを行う場合は）Admin Console でドメイン全体の委任を有効にします
4. キーを 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 では、複数のリクエストを 1 回の 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())
}

制限：

• 1 バッチあたり最大 100 件のリクエスト（ほとんどの API）
• 1 バッチあたり最大 1000 件のリクエスト（Drive など一部の API）
• バッチ内の各リクエストはクォータに加算されます

---

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 か月間使用されていない場合） 対処法：ユーザーを再認証し、新しい更新トークンをリクエストします

エラー：「access_denied」（OAuth 時）

原因：アプリが未認証であるか、ユーザーがテストユーザーリストに含まれていません 対処法：OAuth 同意画面のテストユーザーにユーザーを追加するか、アプリの認証を完了します

エラー：「insufficientPermissions」（403）

原因：必要なスコープがありません 対処法：認証 URL のスコープを確認し、正しいスコープで再認証します

エラー：「rateLimitExceeded」（403）

原因：クォータを超過しました 対処法：指数バックオフを実装し、リクエスト頻度を下げ、クォータの引き上げを申請します

エラー：「notFound」（404）が既知のリソースで発生する

原因：API バージョンが間違っているか、リソースがゴミ箱にあります 解決方法：URL の API バージョンを確認し、削除されたアイテムがゴミ箱にないか確認します

---

API 固有のガイド

各 API の詳細なパターンについては、references/ ディレクトリを参照してください。特定の API を扱う際に、これらを読み込んでください。

Gmail API

references/gmail-api.mdを参照してください

• メッセージの CRUD、ラベル、スレッド
• MIME の処理、添付ファイル
• プッシュ通知（Pub/Sub）

Calendar API

references/calendar-api.mdを参照してください

• イベントの CRUD、繰り返しイベント
• 空き時間のクエリ
• カレンダーの共有

Drive API

references/drive-api.mdを参照してください

• ファイルのアップロード／ダウンロード
• 権限、共有
• 検索クエリ

Sheets API

references/sheets-api.mdを参照してください

• セルの読み取り／書き込み
• A1 表記、範囲
• 一括更新

Chat API

references/chat-api.mdを参照してください

• ボット、ウェブフック
• Cards v2、インタラクティブフォーム
• スペース、メンバー、リアクション

(MCP サーバーの構築に伴い、API のリファレンスを追加します)

---

パッケージバージョン（2026-01-09 確認済み）

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

---

公式ドキュメント

• 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

---

スキルのロードマップ

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