google-services-mcps

Architecture

How the pieces connect

The suite has three layers, and the generated plugin folders are the join point. The marketplace lists the plugins; a plugin holds one MCP server, a consent hook, a tool map and a skill; the server calls Google with the credentials in the token directory.

The three layers

The layers of the suite
LayerWhat it isExample
MarketplaceThe google-services-mcps catalogue in .claude-plugin/marketplace.json. It lists the 23 plugins.claude plugin marketplace add
PluginOne Google product, packaged for Claude Code. It holds the MCP server, a consent hook, a tool map and a skill.gmail@google-services-mcps
MCP serverA local Node.js process. The agent starts it over stdio. It exposes the product's tools and calls Google's APIs.servers/gmail.mjs

The same servers run in Claude Code, Codex, OpenCode and Antigravity. Claude Code installs whole plugins from the marketplace. The installer writes the other three agents' config files and copies each product's server files to ~/.google-services-mcps/runtime/<product>/. The hook exists only in Claude Code.

The plugin-to-harness map Twenty-three product plugin folders, grouped by login group, each starting one MCP server. Claude Code starts the server through the plugin and its PreToolUse hook; Codex, OpenCode and Antigravity start the same server from a runtime copy with no hook. PRODUCT PLUGINS (23) MCP SERVER HARNESS cloud gcloud · gai searchconsole gsc workspace-user gdrive · gmail · gcalendar · gchat · gmeet gcontacts · gtasks · gclassroom · gapps workspace-admin gadmin business ganalytics · gtm · gyoutube · gbusiness gads developer gfirebase service-account gplay · gmerchant apikey gsearch · gmaps one server per product servers/<id>.mjs stdio, local Node.js process tool-map.json every tool, its class, its scopes scopes.json the OAuth scopes of each API servers.json APIs, gateway APIs, login group token directory ~/.google-services-mcps Google APIs HTTPS, with your credentials no server of the suite's own no telemetry path Claude Code marketplace → plugin → server PreToolUse hook asks before a change destructive actions ask twice Codex config.toml → runtime copy no hook; changes need MCP elicitation OpenCode opencode.json → runtime copy no hook; changes need MCP elicitation Antigravity mcp_config.json → runtime copy global scope only; no hook LEGEND OAuth user login service account, domain-wide service account key or API key
The 23 product folders, one MCP server each, and the four harnesses. Claude Code adds the consent hook; the other three have none.

The install flow

Every route runs the same installer. It checks the requirements of the agents you chose before it writes anything, then installs the plugin or writes the agent's config, then records the install. Logins and tokens are never touched.

The install flow The npx command runs the gsm installer, which checks the agent requirements before writing anything. Claude Code installs the marketplace and the plugin; Codex, OpenCode and Antigravity get a runtime copy and a config entry. The installer records the install and never touches the token directory. INSTALL FLOW 1. command npx google-services-mcps install --agent … --plugin … 2. requirements claude / codex / opencode git, when the marketplace is remote 3. install plugin, or agent config and a runtime copy 4. install record runtime/installs.json read by list and uninstall Claude Code claude plugin marketplace add google-services-mcps claude plugin install <id>@google-services-mcps --scope … writes: Claude Code's own settings files the plugin is read from the marketplace Codex, OpenCode, Antigravity copy plugins/<id> → ~/.google-services-mcps/runtime/<id>/ write one entry into the agent's config file config.toml · opencode.json · mcp_config.json a backup of each changed file is kept Never touched by install or uninstall the token directory (~/.google-services-mcps): OAuth client, login tokens, API key, policy.json, audit.log. Log in separately, once per group. Sign in, once per login group setup-client, then login <group> · setup-admin · setup-service-account · setup-apikey
From the npx command to the agent configuration: the requirements check, the two install paths, and the install record.

The auth model

There are three kinds of credential, and a product belongs to one login group that decides which kind it uses. A Desktop OAuth client gives a user token per group; a service account key covers Google Play and Merchant Center; an API key covers the public search and maps APIs. Tokens, the client file and the API key stay in the token directory; the suite has no server of its own and no telemetry path.

The auth model Three credential kinds — a Desktop OAuth client per login group, a service account key, and an API key — feed the token directory. The MCP server reads the tokens and calls Google over HTTPS. Every change passes the gate: token scopes, tool registration, the approval hook, the confirmation setting, the policy file and the audit log. AUTH MODEL Desktop OAuth client one per Google Cloud project one login per group: cloud, searchconsole, workspace-user, business, developer Service account key domain-wide delegation: workspace-admin a key file: service-account (gplay, gmerchant) API key apikey group: gsearch, gmaps token directory ~/.google-services-mcps client_secret.json <group>.token.json apikey.json workspace-admin.scopes.json service-account.json policy.json audit.log mode 0600 where supported; on Windows, a limited access list MCP server local Node.js process reads the token for its group registers only the tools the token covers calls Google over HTTPS retries 429, 503 and read 403s, 3 attempts redacts credential fields in read results Google APIs OAuth tokeninfo scope checks quotas billing approval rules The gate: every change, in order 1. token scopes — Google rejects a call outside them 2. tool registration — write and destructive tools are hidden while Allow write tools is off 3. approval — the PreToolUse hook asks and never allows; a destructive call also shows an exact form 4. confirmation — every-change, destructive-only or off 5. policy.json — deny wins, then ask, then allow 6. audit.log — one line, a hash of the arguments, never the values
Three credential kinds feed the token directory, the server reads them, and the gate decides every change before it reaches Google.

A tool call passes through the layers in order. The token scopes decide what Google will accept. The server lists a write or destructive tool only when Allow write tools is on. In Claude Code, the PreToolUse hook asks before a change and never allows a call, so your own permission rules still apply. A destructive action also shows an Approve this action? form with the exact action. The confirmation setting and the policy file decide whether a prompt is needed, and each gated action writes one line to audit.log.

  1. Token scopes. A login asks only for the scopes of its profile. Google rejects any call outside them, whatever the plugin shows.
  2. Tool registration. Write and destructive tools are hidden while Allow write tools is off.
  3. Approval gate. The hook returns ask or deny, never allow. A destructive call also shows the exact action in a form.
  4. Confirmation and policy. confirmation sets when to ask; policy.json holds allow, ask and deny rules, and a deny always wins.
  5. Audit log. One JSON line per gated action, with a hash of the arguments, never the values.

The plugin folder

Every plugin folder has the same shape. The files are generated by the build, and the plugin's manifest points at the parts.

What a plugin folder holds
PathWhat it is
.claude-plugin/plugin.jsonthe plugin manifest: name, display name, version, description, options
.mcp.jsonhow the agent starts the server, and which plugin options become environment variables
servers/<id>.mjsthe MCP server, bundled so it needs no node_modules
hooks/hooks.jsonthe PreToolUse matcher for this plugin's tools
bin/gsm-hook.mjsthe hook: it reads the tool map and the policy, and asks or denies
tool-map.jsonevery tool name, its safety class and its scopes
method-kinds.jsonthe safety class of the product's API methods
servers.jsonthe server, its APIs, its gateway APIs and its login group
scopes.jsonthe OAuth scopes of each API
skills/<id>/SKILL.mdthe skill: when to use the product and the common tasks

Where the data goes

The servers call only Google's API and OAuth endpoints, and the code has no separate telemetry path. Tokens stay in the token directory on your machine. Anything a tool returns, such as mail text, becomes part of the agent's conversation, so it goes to that agent's model provider as usual.

The configuration page lists the settings and the environment variable names. The troubleshooting page covers the messages the suite prints when a layer refuses a call.