Skills — Google Workspace

Concept: @theokit/skills-google-workspace is a skills bundle, not a gateway. Gateways carry user conversation into the agent; skills are tools the agent uses. Use this package when you want your agent to read your calendar, summarize a Doc, append rows to a Sheet, etc.

A single workspace package that emits one McpServerConfig running the google-workspace-mcp server (pm990320, MIT, GitHub Actions OIDC trusted publisher). One subprocess covers seven Google products. Read-only is the default per ADR D343.

Quick start

pnpm add @theokit/skills-google-workspace
npx theokit setup gworkspace   # validates OAuth client + delegates to upstream installer

import { Agent } from "@theokit/sdk";
import { googleWorkspace } from "@theokit/skills-google-workspace";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: { id: "openai/gpt-4o-mini" },
  mcpServers: googleWorkspace(),   // read-only by default
});

const reply = await (await agent.send("What's on my calendar tomorrow?")).wait();
console.log(reply.result);
await agent.dispose();

Tools exposed

The upstream server provides 95+ tools across:

Read-only by default (ADR D343)

googleWorkspace()                // safe — write tools return errors
googleWorkspace({ writable: true }) // unlocks Drive write, Gmail send, Calendar create, ...

The OAuth consent grants broad scopes (the upstream server uses one wide consent screen). --read-only is a runtime safety on top of that, NOT scope narrowing. To genuinely have narrow scopes, manage scope selection inside Google Cloud Console at consent time.

CLI setup walkthrough

npx theokit setup gworkspace

What it does:

1. EC-1 guard (MUST FIX): validates that ~/.google-mcp/credentials.json is a Desktop application OAuth client (not the Web application type that silently fails downstream). Bails with an actionable error if the wrong type is detected.
2. EC-2 guard: validates JSON shape before shelling out.
3. Delegates to npx google-workspace-mcp setup and accounts add default for the actual OAuth dance.

Flags:

• --probe — runs npx google-workspace-mcp status after staging (10s timeout per upstream call).
• --credentials-path <path> — override the default ~/.google-mcp/credentials.json.
• --non-interactive — refuses prompts; suitable for CI.
• --writable calendar,drive — informational only; the actual write toggle lives in your googleWorkspace({ writable: true }) call.

Multi-account

npx google-workspace-mcp accounts add work
npx google-workspace-mcp accounts add personal

const workAgent = await Agent.create({
  apiKey: ...,
  mcpServers: googleWorkspace({ account: "work" }),
});

The factory keys the MCP server under gworkspace-work (or gworkspace for the default account), so it does not collide with other agents.

ADRs

• D340 — separate workspace package (matches gateway-* pattern, D170/D171)
• D341 — single factory returns Record<string, McpStdioServerConfig>
• D342 — stdio launch via npx google-workspace-mcp serve
• D343 — read-only-by-default
• D344 — credentials at upstream default ~/.google-mcp/credentials.json
• D345 — OAuth delegated to upstream accounts add CLI
• D346 — theokit setup is a new CLI verb (future-proofs setup notion, setup linear)
• D347 — six cookbook recipes, last one combines Calendar + Drive
• D348 — package version 0.1.0 per D181 pre-1.0 policy

See also

• examples/skills-google-workspace/ — six recipes
• @theokit/skills-google-workspace — package source
• Upstream MCP server: github.com/pm990320/google-workspace-mcp