Quick start

This walkthrough sets up Gmail for Claude Code and proves the chain: marketplace, plugin, server, login and API call. It needs Node.js 20 or newer, Claude Code 2.1.271 or later, a Google account (a Google Workspace account is the main target) and no clone. The commands run with npx.

1. Install the Gmail plugin

The first install also adds the marketplace, so there is no separate step. Leave Allow write tools off for now, keep Confirm before changes at every-change, and leave the token directory empty.

npx google-services-mcps install --agent claude --plugin gmail

2. Create a Desktop OAuth client

In the Google Cloud console, create a project for the suite and enable the Gmail API. Configure the OAuth consent screen: use Internal for a Workspace domain, and publish an external app, because an app left in Testing loses its refresh token after 7 days. Create an OAuth client ID of type Desktop app and download its JSON file.

3. Save the client file and log in

setup-client copies the file into the token directory as client_secret.json, with mode 0600 where the platform supports it. The login asks only for the scopes of its profile; readonly is the default.

npx google-services-mcps setup-client path/to/client_secret.json
npx google-services-mcps login workspace-user --profile readonly --servers gmail
npx google-services-mcps status

The login opens a browser. Approve the Google consent screen. The redirect goes to 127.0.0.1 on the machine that runs the command, so the browser must be on that machine. status then shows the group as logged in.

4. Restart Claude Code and check the server

Start Claude Code in your working folder and run /mcp. The gmail server should show as connected. If the server was already running before the login, reconnect it there or restart Claude Code. From a terminal, claude plugin list and npx google-services-mcps list show the install.

5. Run one read

Ask Claude:

Claude calls read tools such as mcp__plugin_gmail_gmail__gmail_users_messages_list. Reads never ask for approval. When this works, every layer is in place.

If it goes wrong

• The tools do not appear. Run claude plugin list; if the status is disabled, enable it with claude plugin enable gmail@google-services-mcps --scope user. Then run /mcp and read the message there.
• The server shows no tools. Check that the server is on in /mcp, that the plugin is enabled, and that the login profile covers the tools you expect. A readonly login lists only read tools.
• Every call fails with a login message. Set up the client and log in for the group. npx google-services-mcps doctor --plugin gmail checks the plugin folder and the credentials.
• The browser does not open. Run the login again with --no-browser; it prints the URL to open on the same machine.

The troubleshooting page has the exact messages and their fixes. The install page covers the other agents and scopes, and the products page lists what each plugin adds.