MCP Configuration for Google Workspace with Claude Code

A developer published a Claude Code skill and plugin that automates connecting Google Workspace's eight remote MCP servers — Gmail, Drive, Docs, Sheets, Slides, Calendar, Chat and People — to Claude Code, enabling the required APIs, registering the servers, handling OAuth sign-in and testing each one. All eight servers passed a read-only test, though the setup is limited by roughly one-hour sign-in sessions and a People sign-in that revokes previously issued tokens, so People must be authenticated first.

This article provides a step by step configuration guide for the Google Workspace remote MCP servers with Claude Code. The setup is packaged as a Claude Code skill and plugin, so Claude Code can enable the APIs, register the servers, sign in, and test all eight of them. https://github.com/xbill9/workspace-mcp-claude https://github.com/xbill9/workspace-mcp-claude All eight Workspace servers pass a read-only test from Claude Code. Two sign-in limits shape how you use them: each sign-in lasts about an hour, and signing People in again revokes every token issued before it, so People always goes first. Yes The first two versions of this setup used Gemini CLI and Antigravity CLI: MCP Configuration for Google Workspace with Gemini CLI https://medium.com/google-cloud/mcp-configuration-for-google-workspace-with-gemini-cli-ead9ebdc5903 MCP Configuration for Google Workspace with Antigravity CLI https://dev.to/gde/mcp-configuration-for-google-workspace-with-antigravity-cli-3f34 This version moves the same Google Cloud project to Claude Code, brings in the three newer servers Docs, Sheets and Slides and Chat, which the earlier config files left out, and packages it all as a Claude Code skill. Google hosts one remote MCP server per Workspace product. Getting Claude Code connected takes a Google Cloud project with the right APIs, an OAuth web client, a few console settings, the servers registered in Claude Code, and a browser sign-in per server. The repository turns that into scripts and a skill. The scripts do everything that has an API. The skill tells Claude Code how to check what is already done, run the scripts, walk through the console steps, and test the result. Google Workspace is Google's subscription productivity suite: Gmail, Drive, Docs, Sheets, Slides, Calendar, Chat and Meet on a custom domain, with admin controls and shared storage. Google Workspace: Secure Online Productivity & Collaboration Tools https://workspace.google.com/ Workspace MCP support is in Developer Preview. Sign up here before starting: Google Workspace Developer Preview Program https://developers.google.com/workspace/preview gcloud , signed in. cd ~ git clone https://github.com/xbill9/workspace-mcp-claude cd workspace-mcp-claude | Server | URL | Tools | |---|---|---| | gmail | https://gmailmcp.googleapis.com/mcp/v1 | 23 | | drive | https://drivemcp.googleapis.com/mcp/v1 | 8 | | docs | https://docsmcp.googleapis.com/mcp/v1 | 2 | | sheets | https://sheetsmcp.googleapis.com/mcp/v1 | 6 | | slides | https://slidesmcp.googleapis.com/mcp/v1 | 4 | | calendar | https://calendarmcp.googleapis.com/mcp/v1 | 9 | | chat | https://chatmcp.googleapis.com/mcp/v1 | 4 | | people | https://people.googleapis.com/mcp/v1 | 3 | A ninth server, workspace-developer at https://workspace-developer.goog/mcp , searches the Workspace developer docs and needs no sign-in. The tool counts come from mcp probe.sh , shown later. Each product needs its API and its MCP service. People serves MCP from people.googleapis.com , so the total is 15 services. bootstrap.sh enables them with gcloud: ./bootstrap.sh Updated property core/project . Enabling Workspace APIs and MCP services on comglitn Operation "operations/acat.p2-<project-number -d46329d0-40b5-4232-a430-c43e10731dc2" finished successfully. When gcloud cannot sign in from the current shell, one console URL enables all 15 at once: https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com,drive.googleapis.com,docs.googleapis.com,sheets.googleapis.com,slides.googleapis.com,calendar-json.googleapis.com,chat.googleapis.com,people.googleapis.com,gmailmcp.googleapis.com,drivemcp.googleapis.com,docsmcp.googleapis.com,sheetsmcp.googleapis.com,slidesmcp.googleapis.com,calendarmcp.googleapis.com,chatmcp.googleapis.com&project=PROJECT ID In the Google Cloud console, open Google Auth Platform → Branding and click Get Started if it is not configured. Name the app Workspace MCP Servers , pick Internal for the audience, and add a contact email. Then Data Access → Add or remove scopes → Manually add scopes , and paste the scopes for the servers you want. Prefix each with https://www.googleapis.com/auth/ : | Server | Scopes | |---|---| | gmail | gmail.readonly , gmail.compose | | drive | drive.readonly , drive.file | | docs | drive scopes, documents.readonly , documents | | sheets | drive scopes, spreadsheets.readonly , spreadsheets | | slides | drive scopes, presentations.readonly , presentations | | calendar | calendar.calendarlist.readonly , calendar.events.freebusy , calendar.events.readonly | | chat | chat.spaces.readonly , chat.memberships.readonly , chat.messages.readonly , chat.messages.create , chat.users.readstate | | people | directory.readonly , userinfo.profile , contacts.readonly | That is 21 distinct scopes. The sensitive-scopes table on the Data Access page shows 10 rows per page, so three of them land on page 2. Google Auth Platform → Clients → Create Client . Pick Web application and add two authorized redirect URIs: http://localhost:8765/callback for Claude Code. The port matches CALLBACK PORT in the scripts. https://claude.ai/api/mcp/auth callback for claude.ai and Claude Desktop custom connectors. Leave "This client will be used by an AI-powered agent" unticked. Google's guide leaves it off. The Chat server needs a Chat app in the project. Open Google Chat API → Manage → Configuration and set: Chat MCP https://developers.google.com/chat/images/quickstart-app-avatar.png Chat MCP server Leave "Build this Chat app as a Workspace add-on" as it is. Clearing it cannot be undone. The console shows a client secret once, when it is created. On a later visit the client page says viewing and downloading secrets is no longer available, and Add secret creates a new one with a download button. The download lands in ~/Downloads as client secret <client-id .json or client secret <n <client-id .json . bootstrap.sh picks up the newest one. bootstrap.sh installs the client from the downloaded JSON into ~/client id.txt and ~/client secret.txt mode 600, never printed , then registers the servers with claude mcp add-json : ./bootstrap.sh --no-apis --no-login Installing OAuth client from /home/xbill/Downloads/client secret 2 <project-number -<client .apps.googleusercontent.com.json Saved client <project-number -… to ~/client id.txt and ~/client secret.txt Adding Workspace MCP servers to Claude Code scope: local Redirect URI required on the OAuth client: http://localhost:8765/callback gmail: https://gmailmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected drive: https://drivemcp.googleapis.com/mcp/v1 HTTP - ✔ Connected docs: https://docsmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected sheets: https://sheetsmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected slides: https://slidesmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected calendar: https://calendarmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected chat: https://chatmcp.googleapis.com/mcp/v1 HTTP - ✔ Connected people: https://people.googleapis.com/mcp/v1 HTTP - Needs authentication workspace-developer: https://workspace-developer.goog/mcp HTTP - ✔ Connected Each server gets its scopes pinned in oauth.scopes and the fixed callback port. Claude Code keeps the client secret in its own credential store, so nothing secret reaches .mcp.json or ~/.claude.json . MCP SCOPE picks where the servers live: user the default, every project , local this directory only or project a shared .mcp.json . Sign in People before the other seven. A repeat People sign-in revokes every token issued before it, so the order matters every time you sign in again. The known issues below have the measurements. From your own terminal, in the repository directory: for s in people gmail drive docs sheets slides calendar chat; do claude mcp login $s; done Or run /mcp inside Claude Code and pick Authenticate on each server, People first. Claude Code can also do it for you through the Chrome extension. claude mcp login needs a terminal, so mcp login.sh runs it under a pseudo-terminal and prints the Google sign-in URL for Claude to open. check confirms once Allow has been clicked: ./mcp login.sh start people ./mcp login.sh check people https://accounts.google.com/o/oauth2/v2/auth?response type=code&client id=<id &code challenge=<… &code challenge method=S256&redirect uri=http%3A%2F%2Flocalhost%3A8765%2Fcallback&state=<… &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcontacts.readonly&resource=https%3A%2F%2Fpeople.googleapis.com%2Fmcp Signed in: people The consent page is a grant of access to your mail, files and calendar. Check the permissions it lists against the scope table before clicking Allow . mcp status.sh lists each server's sign-in. --verify asks Google whether each token is still accepted, printing only valid or invalid: ./mcp status.sh --verify server registered token min left refresh gmail yes valid 50 no drive yes valid 51 no docs yes valid 52 no sheets yes valid 53 no slides yes valid 54 no calendar yes valid 54 no chat yes valid 55 no people yes valid 49 no 8 of 8 servers hold a token Google accepts. Tokens without refresh expire after about an hour; sign in again with /mcp or mcp login.sh when they do. mcp test.sh runs one headless Claude Code session allowed only read-only tools, asks it to make one call per server, and grades each server from the tool results in the session's event stream. The model's own summary plays no part in the grade: ./mcp test.sh Testing: gmail drive docs sheets slides calendar chat people server result ok err tools gmail PASS 1 0 list labels drive PASS 4 0 list recent files, search files docs PASS 1 0 read doc sheets PASS 1 0 get spreadsheet slides PASS 1 0 read presentation calendar PASS 1 0 list calendars chat PASS 1 0 search conversations people PASS 1 0 get user profile 8 of 8 servers passed. exit=0 Drive shows four calls because its file search also finds the Doc, Sheet and Slides deck the next three checks read. ./mcp test.sh slides tests one server. With the servers signed in, restart Claude Code in the repository directory so their tools load, and ask in plain language. Each demo below shows the prompt, the tools Claude Code called, and its answer. They come from docs/article/run-demo.sh , which runs a prompt through a headless session limited to the tools named after it. docs/article/run-demo.sh "According to my Google profile, what is my name?" "mcp people get user profile" According to my Google profile, what is my name? ✅ mcp people get user profile Your Google profile name is xbill work account xbill@glitnir.com . Two servers work together here: Drive finds the newest presentation and Slides reads it. docs/article/run-demo.sh "Find my most recent Google Slides presentation and give me its title, its slide count, and a three-bullet summary of what it covers." "mcp drive search files,mcp slides read presentation" Find my most recent Google Slides presentation and give me its title, its slide count, and a three-bullet summary of what it covers. ✅ mcp drive search files ✅ mcp drive search files ✅ mcp slides read presentation ✅ Bash echo "30 37 12 0 30 0 30 8 30 13 30 19 30 25 30 43 30 51 30 57 30 63 30 68 30 73 30 78 30 83 30 92 30 88 30 97 30 102 30 107 30 113 30 118 30 136 30 142 30 162 5 0 30 153 30 158 32 0" | wc -w Your most recent presentation is Gemma4 Local . It was last modified 2026-10-01 and you last opened it today. A Drive search for presentations modified after that date returned only this deck, so nothing newer exists. - Title: Gemma4 Local. The subtitle is "Deploying next-generation open-weights models on local hardware environments." - Slide count: 29. I counted the slide IDs the Slides API returned with wc . Eight of the 29 slides have no text, so they're probably images or screenshots. The summary below comes from the text on the other slides. What it covers: - The Gemma 4 model family. It explains what Gemma is: open weights under the Apache license, and a separate model from Gemini. It then goes through the sizes: E2B and E4B for edge devices, the 26B A4B mixture-of-experts model, and the 31B dense model. It also includes two newer additions: the 12B mid-size model and quantization-aware training QAT to shrink the weights for low-end hardware. - Ways to access and host it. Options include AI Studio, Model Garden, local hosting Ollama, vLLM, Docker, Edge Gallery on mobile and Google Cloud. On Google Cloud that means TPUs v5e, v5p, v6e, Ironwood , Cloud Run with L4 or 96 GB GPUs, VMs with attached GPUs, and GKE. - Live demos and next steps. The demos are a self-contained Tesla T4 VM on Google Cloud and a 4 GB laptop GPU running a QAT model, plus others in the repo across Cloud Run, GKE, TPU, AWS and Azure. The "Future" slide lists a vLLM QAT TPU pull request, a v5e deep dive, a v6e comparison, QAT and GGUF repacks, JAX on AWS Inf2, and a "lite" GKE demo. The deck opens with your speaker slides bio, where to find you, recent articles . link to the deck removed Claude counted the slides with wc over the IDs Slides returned, so the 29 comes from the tool output. Ask for the count Gmail's own search returns, so the number comes from Gmail: docs/article/run-demo.sh "How many unread threads are in my Gmail inbox? Use the count the Gmail search returns rather than counting results yourself. Reply with the number and the query you used, and nothing about the individual emails." "mcp gmail search threads" How many unread threads are in my Gmail inbox? Use the count the Gmail search returns rather than counting results yourself. Reply with the number and the query you used, and nothing about the individual emails. ✅ mcp gmail search threads Gmail's search returned 2 unread threads in your inbox. - Query: in:inbox is:unread - Count: resultCountEstimate: "2" . That's the number Gmail reported, and it's labelled an estimate. One of the two threads that came back no longer has the UNREAD label, so it was probably read recently and the search index hasn't caught up. The live number may be 1. Calendar's suggest time searches for free time. The pinned Calendar scopes are read-only, so nothing can be booked: docs/article/run-demo.sh "Suggest a free 30-minute slot for a meeting tomorrow afternoon on my primary calendar. Read only, do not create anything." "mcp calendar list calendars,mcp calendar suggest time" Suggest a free 30-minute slot for a meeting tomorrow afternoon on my primary calendar. Read only, do not create anything. ✅ mcp calendar list calendars ✅ mcp calendar list events ✅ mcp calendar suggest time I suggest Monday, October 5, 2:00–2:30 PM Eastern . Your primary calendar xbill@glitnir.com, Eastern time has one event tomorrow afternoon: TPU Office Hours, 1:30–2:00 PM . I asked Calendar's free-time search for openings between noon and 5 PM, and it returned two: - 🟢 12:00–1:30 PM 90 minutes - 🟢 2:00–5:00 PM 3 hours I picked 2:00 PM because it starts the longest open stretch, so the meeting can run over without a conflict. 12:00–12:30 is also free if you'd rather go before the office hours. ⚠️ You haven't responded to the TPU Office Hours invite yet, but Calendar still counts it as busy. If you skip it, 12:00–5:00 is open, apart from that one half-hour. This only read your calendar. I didn't create or change anything. The 2026-07-28 MCP specification makes the protocol stateless: a server/discover request replaces the initialize handshake. mcp probe.sh checks each server with no credentials: ./mcp probe.sh server 2026-07-28 legacy init tools gmail yes 2025-11-25 23 drive yes 2025-11-25 8 docs yes 2025-11-25 2 sheets yes 2025-11-25 6 slides yes 2025-11-25 4 calendar yes 2025-11-25 9 chat yes 2025-11-25 4 people no 2025-11-25 3 7 of 8 servers advertise 2026-07-28; 59 tools in total. Seven servers advertise 2026-07-28 and Claude Code connects to those at that version. People answers only the 2025-11-25 handshake. All eight accept 2025-11-25, so any current MCP client connects. The repository is also a Claude Code plugin marketplace. Install the google-workspace-mcp skill from inside Claude Code: /plugin marketplace add xbill9/workspace-mcp-claude /plugin install google-workspace-mcp@workspace-mcp-claude To try it from a clone without installing, start Claude Code with claude --plugin-dir ~/workspace-mcp-claude/plugin . The skill finds its scripts relative to its own directory either way. The manifests and the skill validate: claude plugin validate . claude plugin validate plugin claude plugin validate plugin/skills Validating marketplace manifest: /home/xbill/workspace-mcp-claude/.claude-plugin/marketplace.json ✔ Validation passed Validating plugin manifest: /home/xbill/workspace-mcp-claude/plugin/.claude-plugin/plugin.json ✔ Validation passed Validating components in: /home/xbill/workspace-mcp-claude/plugin/skills ✔ Validation passed The skill loads when a request is about connecting, signing in to, testing or fixing the Workspace servers, even when it never says "MCP": | Ask | What the skill does | |---|---| | "Connect my Gmail and Drive to Claude Code" | checks what exists, then walks the missing steps in order | | "Is my Google Workspace MCP setup working?" | runs mcp status.sh --verify and mcp test.sh | | "My Gmail tools disappeared" | checks for revoked or expired tokens and says which servers to sign in again | | "Sign my Workspace servers back in" | People first, then the other seven | | "Gmail says insufficient scope" | names the scope to add in claude setup.sh and on the consent screen | It always starts by finding out what is already done, because setup is usually half finished: a project with the APIs on, a client from an earlier tool, servers registered for another directory. Asked from the home directory, with no setup files in sight, the skill loads, finds the servers registered for the repository directory, and checks them without changing anything. Trimmed: Is my Google Workspace MCP setup for Claude Code working? Check it, but do not sign anything in or change anything. ✅ Skill google-workspace-mcp:google-workspace-mcp ✅ Bash "/home/xbill/workspace-mcp-claude/plugin/skills/google-workspace-mcp/scripts/mcp status.sh" --verify; … ✅ Bash claude mcp list 2 &1 | head -40; … ✅ Bash cd /home/xbill/workspace-mcp-claude && "/home/xbill/workspace-mcp-claude/plugin/skills/google-workspace-mcp/scripts/mcp test.sh"; … Yes, it works. All eight Workspace servers answered a real read-only call, and Google accepts all eight sign-ins. I didn't sign in or change anything. Sign-ins mcp status.sh --verify : all 8 servers are registered and Google accepts all 8 tokens. They have about 38–43 minutes left People and Gmail run out first , with no refresh token. After that they show "Needs authentication", and you'll need to sign in again with /mcp . Sign in to People first, because a repeat People sign-in makes Google revoke the tokens of the other servers. - The servers only exist in ~/workspace-mcp-claude . They're registered with local scope, so from any other directory including ~ , where I started claude mcp list doesn't show them and their tools aren't available. If you want Gmail and Drive everywhere, re-register them with MCP SCOPE=user . Moving the servers to user scope drops their sign-ins and their client secret, because both are stored per server name. Remove the local copies, run MCP SCOPE=user ./claude setup.sh once more, then sign in to all eight again, People first. | File | Purpose | |---|---| | SKILL.md | the workflow: check first, then APIs, console, secret, register, sign in, test | | scripts/bootstrap.sh | APIs, client install, registration, sign-in People first | | scripts/claude setup.sh | registers the eight servers plus workspace-developer with pinned scopes | | scripts/mcp login.sh | sign-in without a terminal: prints the Google URL, then confirms | | scripts/mcp status.sh | sign-in state per server; --verify asks Google | | scripts/mcp test.sh | one read-only call per server, graded from the tool results | | scripts/mcp probe.sh | MCP versions and tool lists, no credentials needed | | references/console-setup.md | the console steps, with the exact URLs and settings | | references/servers.md | server URLs, the 21 scopes, tool lists | | references/known-issues.md | the two sign-in limits, with the measurements | | references/quirks.md | every other quirk seen during setup | The scripts at the repository root are wrappers around these, so a plain clone works the same way. The skill stops at three points, each for a reason: Google issues these sign-ins without a refresh token, so Claude Code cannot renew them. Every Workspace entry in Claude Code's credential store has an access token and an expiry one hour after sign-in, and no refresh token. The authorization URL Claude Code builds carries response type , client id , PKCE, redirect uri , state , scope and resource . Google issues a refresh token only when the request also asks for offline access access type=offline , and Claude Code's oauth settings clientId , callbackPort , scopes , authServerMetadataUrl have no field that adds it. Plan for a fresh sign-in each working hour. mcp status.sh shows the minutes left. Signing People in again makes Google revoke the token of every server signed in before it, while those tokens still have most of their hour left. Sign-ins for the other seven revoke nothing. Each row below was checked with Google's token-info endpoint: | Sign-in order | Tokens Google accepts afterwards | |---|---| | All eight, People last, first sign-in for each | 8 of 8 ✅ | | People again | People only ❌ | | All eight again, People last | 7 valid until People, then People only ❌ | | People first, then the other seven | 8 of 8 ✅ | People's repeat sign-in shows one extra step: a "Sign in to Workspace MCP Servers" page with your name and profile picture, and a profile scope added to the grant. Why Google revokes the other tokens is unconfirmed. A revoked server is hard to spot. claude mcp list still shows it ✔ Connected , the stored expiry still shows minutes left, and in a session its tools are simply missing. Claude Code's debug log has the reason: DEBUG MCP server "slides": Connection error: Unauthorized ERROR MCP server "slides" Failed to fetch tools: Unauthorized mcp status.sh --verify reports such a token as revoked . bootstrap.sh and the skill sign People in first. All eight servers list their tools without any token, and seven of them accept Claude Code's connection without one too. So claude mcp list shows those seven ✔ Connected before you sign in and after a token is revoked. People asks Claude Code for a sign-in and shows Needs authentication . Use mcp status.sh --verify for sign-in state and mcp test.sh for working tools. Each server publishes the scopes it accepts. Gmail's list has 11, starting with https://mail.google.com/ , full mailbox access. Without pinned scopes, Claude Code requests what the server's metadata or a 401 response suggests. claude setup.sh pins the scopes from Google's guide for every server. Gmail exposes 23 tools against the 10 the guide lists, and the extra trash, spam and label-editing tools need scopes outside the pinned set. They fail with insufficient scope until you widen that server's entry and sign it in again. When Claude drives the sign-in through Chrome, Google's "Choose an account" page often stays put after the first click on the account. Click the account and press Enter, and repeat once if the chooser is still showing. Chat's consent page lists five permissions and puts Allow below the fold, so scroll first. The skill's references/quirks.md lists every quirk seen during setup. Claude Code's auto mode refuses to read the client secret from the console or from its downloaded file, and refuses to click Add secret . Allowing the tool in /permissions leaves that check in place. So the secret takes one human step: you download it, and bootstrap.sh copies it into ~/client secret.txt without printing it. Delete the downloaded JSON afterwards. | | Gemini CLI | Antigravity CLI | Claude Code | |---|---|---|---| | Server config | .gemini/settings.json , httpUrl | mcp config.json , serverUrl | claude mcp add-json , type: http | | Client secret | ${CLIENT SECRET} from the environment | written into the config file no variable substitution | Claude Code's credential store | | Redirect URI | see the Gemini CLI article | https://antigravity.google/oauth-callback | http://localhost:8765/callback | | Scopes | listed per server | listed per server | pinned per server in oauth.scopes | | Sign-in | /mcp auth <server | /mcp → Authenticate | /mcp , claude mcp login , or mcp login.sh | claude.ai and Claude Desktop take the same eight URLs as custom connectors Settings → Connectors → Add custom connector , with the OAuth client ID and secret under Advanced settings and https://claude.ai/api/mcp/auth callback as the redirect URI. For terminal work in Claude Code, the google-workspace-mcp skill. It registers all eight servers with pinned scopes, keeps the secret out of config files, signs People in first, and proves the result with a read-only test. Plan around the hourly sign-in. mcp status.sh --verify at the start of a session tells you which servers need it, and People first keeps one sign-in from undoing the others. The goal of this article was to connect Claude Code to Google's eight remote Workspace MCP servers and package the setup as a Claude Code skill. The key to the solution was scripting every step that has an API, documenting the console steps that do not, and grading the result from tool calls. The results were: Scope: one Google Workspace account in the Developer Preview, one Google Cloud project with an Internal consent screen and one Web application OAuth client shared by all eight servers, Claude Code 2.1.289 on Linux, checked on 2026-10-04 and 2026-10-05. The revocation was reproduced twice with Google's token-info endpoint; its cause on Google's side is unconfirmed. Separate OAuth clients per server and claude.ai connectors were not tested. The strategy for using MCP with Google Workspace from Claude Code was validated with an incremental step by step approach.