Skip to main content
skill CX Codex

google-workspace · mitsuhiko — Claude Code skill: Google Workspace API access

A skill that gives your agent access to Google Workspace services (Gmail, Drive, Docs, Calendar, Sheets and more) through local helper scripts. Use it to automate Google services directly from your IDE.

Apache-2.0 108 installs ★ 3,224 updated 2026-09-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-code
Open on GitHub

What google-workspace does

google-workspace provides a JavaScript-based bridge to Google Workspace APIs without requiring an MCP server. Two core scripts handle the work: scripts/auth.js manages OAuth login and account enumeration, while scripts/workspace.js runs arbitrary API calls within a JavaScript context.

The skill uses a profile-based model keyed by email address. Every API call requires an --email flag to specify which account to use; tokens are stored separately per email under ~/.pi/google-workspace/tokens/. Before first use, run node scripts/auth.js login --email [email protected] and dependencies will install automatically.

API calls use node scripts/workspace.js exec with a JavaScript block. Inside the script, you have access to workspace.call() for direct API requests, workspace.service() to obtain a service instance, and workspace.whoAmI() to verify the current user. Optional flags include --timeout (default 30000 ms, max 300000) and --scopes to override permissions.

What it helps with

  • List files from Google Drive matching search criteria
  • Send an email via Gmail and retrieve delivery status
  • Create or update a spreadsheet in Google Sheets
  • Fetch calendar events within a date range
  • Search and update contact information via People API

Example prompts for the agent

  • Get the ten most recently created PDFs from Drive
  • Count unread emails with the invoice label
  • Schedule an event tomorrow at 2 PM and invite [email protected]

How to install google-workspace

1Skills CLI (Vercel)

npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-code

2Manually: put the files in place

~/.claude/skills/google-workspace/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/google-workspace/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about google-workspace

How do I install google-workspace in Claude Code?

Run npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-code, then edit the configuration file at ~/.claude/skills/google-workspace/SKILL.md.

What does google-workspace do?

The skill exposes Google Workspace APIs (Drive, Docs, Gmail, Calendar, Sheets, Slides, Chat, People) through local scripts. You write JavaScript code to automate tasks across Google services without needing an MCP server.

Can I use multiple Google accounts at once?

Yes, the skill manages profiles by email address. Each API call takes an --email [email protected] flag to specify which account to use. Run node scripts/auth.js accounts to list all signed-in profiles.

Source text

SKILL.md · Apache-2.0
---
name: google-workspace
description: "Access Google Workspace APIs (Drive, Docs, Calendar, Gmail, Sheets, Slides, Chat, People) via local helper scripts without MCP. Handles OAuth login and direct API calls."
---

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

```bash
node scripts/auth.js accounts
```

## Usage

Always use `exec` and always provide `--email`.

```bash
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:

```bash
node scripts/auth.js accounts
```

2. Retry with the intended account:

```bash
node scripts/workspace.js exec --email [email protected] <<'JS'
return await workspace.whoAmI();
JS
```

3. If token is stale or missing scopes, re-login that account:

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

4. Retry the original request with the same `--email`.

## Short Gmail counting example

```bash
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

```bash
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:

```bash
node scripts/auth.js accounts
node scripts/auth.js status --email [email protected]
node scripts/auth.js clear --email [email protected]
```

© mitsuhiko · Apache-2.0 · mitsuhiko/agent-stuff

Similar skills

All skills for Agent setup: memory, context, orchestration →

google-workspace by other authors comes first.

google-workspace Nous Research google-workspace gives your agent access to Gmail, Calendar, Drive, Docs, Sheets and Contacts through OAuth and a CLI wrapper. Useful for morning briefs and inbox triage. CX Codex +1 620installs google-workspace membrane Skill for Google Workspace: manage users, groups, calendars, Drive files, Gmail and contacts through Membrane CLI. CX Codex +1 274installs google-workspace Agent Skills Team google-workspace is a Claude Code skill that routes Google Workspace work through Apps Script, REST APIs, or Admin SDK. It handles files, mail, calendars, and workflows. CX Codex +1 407installs google-workspace swarmclawai Teaches an agent to drive Google Workspace through the gws CLI: Drive files, docs, spreadsheets, mail, calendar and chat. Useful when a task touches a real Google account. CX Codex +1 ★ 710repo stars google-workspace-cli Alireza Rezvani google-workspace-cli is a Claude Code skill for managing Google Workspace through the gws CLI, including sending Gmail messages and listing Drive files. CX Codex +1 636installs persona-researcher official googleworkspace persona-researcher sets up an AI researcher persona for Google Workspace. It organizes references in Drive, tracks data in Sheets, and manages review requests. CX Codex +1 32,400installs Google Workspace MCP Server conorbronsdon Connects an AI agent to Gmail, Calendar, Drive and other Google Workspace services through 67 MCP tools. Useful for handling mail, files and tasks. CX Codex +1 ★ 13repo stars Workspace Operator Artoxem Workspace Operator — an MCP server for managing Google services via AI agents. Performs bulk operations in Drive, Sheets, Docs, and Gmail with built-in undo support. CX Codex +1 ★ 12repo stars Google Workspace mindstone Google Workspace connects AI agents to Gmail, Drive, Docs, and Calendar. Gives coding assistants access to emails, files, and scheduling via 124 tools. CX Codex +1 ★ 14repo stars persona-content-creator official googleworkspace persona-content-creator — a persona skill that gives an agent the content creator role across Google Workspace. Combines Docs, Drive, Gmail, Chat and Slides workflows into one profile. CX Codex +1 31,900installs

From the same set16

The whole set →

More in the catalog

Project sponsors

Companies that keep this analytics open