google-services-mcps

Troubleshooting

Troubleshooting

Start with the two checks that answer most questions. npx google-services-mcps doctor --plugin <id> checks the plugin folder, the hook, the tool names and the credentials, and exits 1 when a check fails. npx google-services-mcps status shows the logins, the API key and the setup of each group.

The plugin is installed but its tools do not appear

  1. Run claude plugin list. If the status is disabled, enable it: claude plugin enable gmail@google-services-mcps --scope user.
  2. Run claude plugin validate on the plugin folder.
  3. Run /mcp in Claude Code. If the server shows as failed, read the message there.
  4. Run npx google-services-mcps doctor --plugin gmail and fix each FAIL line.

The server shows no tools

  • The server is switched off for this session. Turn it on in /mcp.
  • The plugin is disabled. See the check above.
  • The login uses the readonly profile, so only read tools with read-only scopes are listed. This is expected. Log in with --profile readwrite if you need changes.
  • The group is not logged in. Every tool is listed, but each call fails with Not logged in for "<group>". Set up the client and log in.

Common messages

The message, what it means, and what to do
MessageMeaningWhat to do
Writes are turned off for this server (GSM_ALLOW_WRITES is not "true"), so <tool> was not run.Allow write tools is off.Turn it on in the plugin options and restart the server.
Denied by policy rule "<match>". Nothing was changed.A deny rule matched.Change or remove the rule in policy.json, if you meant to allow the call.
Invalid policy file <path>: ...policy.json is not valid.Fix the JSON or the field named in the error. Changes now ask.
You declined this action. Nothing was changed.You declined the second approval.Nothing to fix. Run the action again if you want it.
This client cannot ask for confirmation, so the action was not run.The client has no approval step.Use Claude Code for changes. Turning confirmation off to get past this is not recommended.
Not logged in for "<group>".No token for the group.Set up the client, then log in for the group.
The token lacks a scope for this tool.The token does not have the scope for this tool.Log in again with --profile readwrite, then restart the server.
HTTP 429 or HTTP 503Google is throttling the call; the suite retried it and it still failed.Wait, then try again. Check the quota in the Cloud console.
A truncated object with shown, omitted and how_to_continueThe result was longer than the result limit (25,000 characters by default).Follow how_to_continue: page on, use a smaller page size, or add a filter.
"<name>" is not a query parameter of this method.api_call was given a query name the method does not declare.Use one of the allowed names from api_describe.
Unknown tool, asking to be safe.The tool is not in this plugin's tool map.Reinstall or update the plugin, then run doctor.
Could not check this action, so asking to be safe.The hook could not read its tool map or policy.Read the error after the message and fix the file it names.

Install and login problems

  • Marketplace not found. Run the install again, which adds the marketplace, or add it by hand with claude plugin marketplace add.
  • setup-client says the file already exists. Use --force. The old client file is backed up first.
  • The browser does not open for login. Run the same login with --no-browser; it prints the URL. Open it on the same machine, because the redirect goes to 127.0.0.1.
  • agy config folder not found. Run Antigravity once so that it creates its config folder, then run the install again.
  • --path must be an existing directory. Create the folder, or fix the path.
  • OpenCode says the file is not strict JSON. Remove the comments or trailing commas from opencode.json, or add the entry by hand. gsm does not change the file.
  • Codex ignores a project config. Codex reads a project .codex/config.toml only in trusted projects. Trust the folder in Codex.
  • --home does not apply to claude. Remove --home when you use --agent claude.

A login works but the tools still fail

After a sign-in in the chat, the server uses the new login at once. After a login in a terminal, call auth_status: it reads the tokens again and loads the tools the new scopes allow. Tools whose scopes the new login lacks stay listed until the server restarts, so restart it in /mcp or restart Claude Code.

If Google refuses the login with a reauthentication request, a Workspace admin setting called Google Cloud session control has ended the session. Its default is 16 hours. Call auth_login to sign in again; to make it last longer, an admin changes the session length or exempts the app.

Rate limits

The suite retries throttled requests on its own, up to three attempts in all. The waits start at 0.5 seconds and double, with jitter; a Retry-After header is used instead, up to 60 seconds. After the last attempt the error text is returned. A quota that is used up resets on Google's schedule. Do not run a loop that retries on its own.

The FAQ answers the broader questions. The configuration page lists the settings that decide when a prompt appears.