google-workspace

Google Workspace MCP server

This server exposes Google Workspace as MCP tools: a small set of curated, hand-written tools per service, a long tail of generated tools (one per Google API Discovery method), and an escape hatch for anything else. Reading this skill before the first call avoids the two most common failures: guessing an account when none was configured as default, and guessing an argument name instead of using the one the tool actually declares.

1. Pick the account

Every operational tool takes an account argument naming one of the configured aliases (an alias is a short local name, not the email address itself). Before calling anything:

1. Call account_list first. It returns each alias, its email, admin flag, token status, and which alias (if any) is the configured default.
2. If a default account is set, omit account on a single-account call; the server injects the default. Passing an alias is always safe too.
3. If no default is set and more than one account is configured, you must pass account explicitly. A call that omits it then fails with E_NO_DEFAULT_ACCOUNT and a hint listing every alias=email pair so you can match the one the user means by email, name, or context, rather than guessing.
4. Read tools accept "*" for the account argument to fan out across every configured account (bounded concurrency), or a comma-separated subset such as "work,personal". Fan-out is read-only by design: write tools, and the handful of read tools that save a file to local disk (drive_download, drive_export, gmail_download_attachment), take exactly one account. A fan-out call returns { results: [{ account, ok, data|error }], partial } so one account failing never hides the others.

2. Discover before calling

Tools are hidden from the model's context until revealed, but every tool is always callable by exact name (discovery is a listing optimization, not a security boundary).

1. Call {service}_discover (e.g. gmail_discover, drive_discover) for the service you need. It returns that service's catalog: each tool's name, a one-line summary, its arguments, and its read/create/update/delete class. An optional query argument filters the catalog by keyword.
2. Call the tool by its exact name from that catalog. Do not guess a name by analogy with another service.
3. discover_all reveals every curated tool across all services at once, useful before a session doing substantial cross-service work, and discover_reset collapses back to the configured default afterward to reclaim context.
4. A client that loads tool schemas on demand (rather than accepting everything a server advertises) may need its own tool-search or tool-load step before a newly revealed tool is actually callable. If a call to a tool you just discovered fails as unknown on such a client, look for that client's own load-tool mechanism before retrying the Google call itself.