mcpField
G
google-workspace

google-workspace

github.com/mitsuhikoProductivity3.2k103 installsUpdated 5w ago
Repository

About google-workspace

google-workspace is a skill for carrying out Google Workspace tasks through its APIs, including Gmail, Drive, Calendar, Docs, and Sheets. It uses email-based profiles, requiring an explicit account for each API call.

Key features

  1. 01Access Workspace APIs through JavaScript
  2. 02Manage OAuth login and account profiles
  3. 03Select an account by email for calls
  4. 04Configure scopes and execution timeouts

Use cases

  1. 01List Drive files for a chosen account
  2. 02Run Gmail queries under a specific profile
  3. 03Make Workspace API calls across services

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mitsuhiko/agent-stuff --skill google-workspace

After installing, type/google-workspacein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

package-lock.json
package.json
scripts/
auth.js
common.js
workspace.js

Details

From the project README

Google Workspace

Use this skill for Google Workspace tasks (Gmail, Drive, Calendar, Docs, Sheets, etc.).

Files

  • scripts/auth.js — OAuth login/status/clear + account enumeration
  • scripts/workspace.js — JavaScript execution based API runner

Account model (multi-account)

This skill is profile-based by email address.

  • There is no default account.
  • Every API call must specify --email <[email protected]>.
  • Tokens are stored per-email under ~/.pi/google-workspace/tokens/.

Before running API calls, discover available signed-in accounts:

node scripts/auth.js accounts

Usage

Always use exec and always provide --email.

node scripts/workspace.js exec --email [email protected] <<'JS'
const me = await workspace.whoAmI();
const files = await workspace.call('drive', 'files.list', {
  pageSize: 5,
  fields: 'files(id,name,mimeType)',
});
return { me, files: files.files };
JS

Available inside exec scripts:

  • auth (authorized OAuth client)
  • google (googleapis root)
  • workspace.accountEmail (selected profile email)
  • workspace.call(service, methodPath, params, {version})
  • workspace.service(service, {version})
  • workspace.whoAmI()

Optional flags:

  • --timeout <ms> (default 30000, max 300000)
  • --scopes s1,s2
  • --script 'return 42'

Agent guidance

  1. Prefer one exec script per user request.
  2. Keep payloads small (fields, maxResults, minimal props).
  3. Use Promise.all for independent requests.
  4. Never print token contents.
  5. If the user did not specify an account, run node scripts/auth.js accounts and choose/confirm an explicit email.
  6. If auth fails, first run node scripts/auth.js accounts to see known profiles.
  7. If account mismatch is possible, run workspace.whoAmI() in the selected profile.
  8. On 401/403/unauthorized errors, switch account (--email ...) or re-login that specific profile.

Unauthorized/account-switch playbook

If a request fails with unauthorized/forbidden/insufficient permissions:

  1. Enumerate profiles:
node scripts/auth.js accounts
  1. Retry with the intended account:
node scripts/workspace.js exec --email [email protected] <<'JS'
return await workspace.whoAmI();
JS
  1. If token is stale or missing scopes, re-login that account:
node scripts/auth.js login --email [email protected]
  1. Retry the original request with the same --email.

Short Gmail counting example

node scripts/workspace.js exec --email [email protected] <<'JS'
const gmail = google.gmail({ version: 'v1', auth });

let trash = 0;
let pageToken;
do {
  const res = await gmail.users.messages.list({
    userId: 'me',
    q: 'in:trash',
    maxResults: 500,
    pageToken,
    fields: 'messages/id,nextPageToken',
  });
  trash += (res.data.messages || []).length;
  pageToken = res.data.nextPageToken;
} while (pageToken);

return { currentlyInTrash: trash };
JS

Setup + auth

node scripts/auth.js login --email [email protected]

Notes:

  • Dependencies auto-install on first run.
  • Default auth mode is cloud (no local credentials.json needed).
  • Optional local mode: GOOGLE_WORKSPACE_AUTH_MODE=local and credentials at ~/.pi/google-workspace/credentials.json.
  • Useful diagnostics:
node scripts/auth.js accounts
node scripts/auth.js status --email [email protected]
node scripts/auth.js clear --email [email protected]

Comments

Markdown supported