Connecting Google Workspace to Claude via MCP: The Setup

The first time Claude searches your Drive and drafts a reply in Gmail without you copy-pasting anything, something clicks. Suddenly the assistant is not a clever chatbox off to the side. It is inside the tools you already use. The bridge that makes this possible is the Model Context Protocol, usually shortened to MCP, and the community Google Workspace MCP server that plugs into it.

This guide walks through the whole setup in prose, without code, aimed at a founder who can edit a text file but does not want to learn OAuth theory. We cover the Google Cloud console trip, the consent screen warning that makes people bail, the Claude Desktop config edit on every major operating system, and a three-prompt test suite that proves each capability separately. At the end we flag the gotchas that tend to bite Workspace Business accounts and chatty sessions.

What you get once this works

With the Workspace MCP server connected, Claude Desktop can do three categories of thing on your behalf. It can search your Drive with natural language, the way you wish Drive's own search worked, and pull the relevant document into the conversation so you can ask questions of it. It can read your calendar and create or move events, which means "block Tuesday morning for deep work" becomes a single sentence. And it can read Gmail threads and prepare drafts that appear in your Gmail drafts folder, ready for you to review and send.

The word "draft" is important. A well-behaved MCP setup never sends mail for you, never deletes files, and never accepts meetings without confirmation. You stay in the loop. Claude prepares, you approve.

Prerequisites

Three things need to be true before you start. You need Claude Desktop installed, which is the macOS, Windows, or Linux app rather than the browser version, because only the desktop app loads MCP servers today. You need a Google account with the Workspace apps you plan to connect, whether that is a personal Gmail or a business Workspace account. And you need roughly twenty minutes of uninterrupted time, because the flow involves switching between the Google Cloud console, a terminal, your file explorer, and Claude Desktop a few times.

If you are on a corporate Workspace where your admin has restricted third-party application access, stop and read the admin-consent section near the end before you start. You may need your IT person to whitelist the app first.

Creating the Google Cloud OAuth client

The MCP server talks to Google's APIs, and Google's APIs want to know which application is asking. That application identity is called an OAuth client, and you create one in the Google Cloud console at console.cloud.google.com.

Start by creating a new project. Name it something you will recognise later, such as Claude Workspace MCP. Inside the project, open the API Library and enable four APIs by name: Gmail API, Google Drive API, Google Calendar API, and Google Docs API. Enabling an API in Google Cloud is free up to the standard per-user quotas and does not start any billing.

Next, open the OAuth consent screen configuration. If you are using a personal Gmail, choose External as the user type, which simply means "not limited to one Google Workspace domain." Fill the required fields with your own details. The app name you pick here is the name your consent screen will display later, so use something like Claude Workspace Connector rather than a dev-internal codename. Add your own email as both the developer contact and the support contact.

When Google asks you to add scopes, this is the moment most tutorials wave through. Scopes are the permissions the app is allowed to request, and you can be selective. For the full suite add drive.readonly for Drive search, gmail.compose for draft creation, and calendar.events for calendar manipulation. If you want Claude to be able to create or edit Drive documents too, add drive.file, which is a narrower scope that only touches files the app itself created. Avoid adding drive full-access unless you know you need it. You can always add scopes later.

Add your own Google email address as a test user. This matters because while the app is in "Testing" mode, only listed test users can authenticate. For a personal setup you never need to submit for verification.

Finally, under Credentials, create an OAuth 2.0 Client ID of type Desktop app. Google hands you a client ID and a client secret. Download the JSON credentials file and save it somewhere you will remember. This file is what the MCP server will use to identify itself to Google.

The OAuth consent screen, the part tutorials skip

The first time you run the Workspace MCP server and it opens a browser window for you to log in, Google will show a screen that says something like "Google hasn't verified this app" with a prominent warning triangle. For a personal OAuth client that has not gone through Google's verification process, this warning is expected and benign. It appears because Google wants users to be cautious about unknown apps, and you are the unknown app.

To proceed, click the small Advanced link at the bottom of the warning, then click Go to Claude Workspace Connector (unsafe), using whatever name you gave the app earlier. Google uses the word "unsafe" to mean "unverified," not "malicious." You know the app is yours because you just created it.

On the next screen Google lists the scopes the app is requesting and asks you to approve them. You can untick individual scopes here if you changed your mind about one of them. The MCP server degrades gracefully: if you decline calendar.events, calendar tools simply fail with a clear permission error, while Drive and Gmail continue to work. This is useful if you want to stage the rollout, connecting Drive first and adding Gmail later once you trust what is happening.

After approval Google redirects to a local URL that the MCP server is listening on, and the server stores a refresh token on your machine so you will not have to repeat this dance. The token cache lives in a hidden folder in your home directory. If you ever want a clean slate, deleting that folder forces a fresh consent flow.

Editing Claude Desktop's config.json

Claude Desktop reads a single configuration file to know which MCP servers to load on startup. The file is called claude_desktop_config.json, and its location depends on your operating system.

On macOS, the path is ~/Library/Application Support/Claude/claude_desktop_config.json. The easiest way to open it is to launch Claude Desktop, open Settings, go to the Developer tab, and click Edit Config, which opens the file in your default editor and creates it if it does not exist.

On Windows, the path is %APPDATA%\Claude\claude_desktop_config.json, which expands to something like C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json. The AppData folder is hidden by default in File Explorer; either enable hidden folders or paste the path into the address bar. The same Settings -> Developer -> Edit Config shortcut works here.

On Linux, the path is ~/.config/Claude/claude_desktop_config.json. If Claude Desktop has never been launched, the Claude folder may not exist yet; create it with your file manager and create an empty file inside.

The file is a single JSON object with a top-level key called mcpServers. Inside that key you add one entry per MCP server, naming it whatever you like. A Workspace MCP entry looks like a short block with three fields: the command that launches the server, the arguments to pass, and an environment variables section that points at your downloaded credentials JSON. A minimal entry reads something like this in shape, not exact syntax:

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS": "/full/path/to/credentials.json"
      }
    }
  }
}

Two things to watch. First, the path to the credentials file must be absolute, not relative, and on Windows you either use forward slashes or escape the backslashes as double backslashes. Second, the command field assumes you have uvx installed, which is the runner that comes with the uv Python tool. If you do not have it, the server's README lists a Node-based alternative that uses npx instead.

After saving the file, quit Claude Desktop completely. On macOS that means Claude -> Quit Claude, not just closing the window. On Windows it means right-clicking the tray icon and choosing Quit. Relaunch, open any conversation, and look for the small hammer or plug icon that indicates tools are available. Clicking it should list the Workspace tools by name.

The three-prompt verification suite

Connecting is not the same as working. Three short prompts will exercise each permission category independently and make failures easy to diagnose.

The first prompt tests Drive search. Ask Claude something like: find the most recent document in my Drive that mentions pricing and summarise the last section. Claude should call a search tool, show you the results, read the winning document, and produce a summary. If search returns empty when you know the document exists, the most common cause is that you granted drive.file instead of drive.readonly, which means the app can only see files it created.

The second prompt tests calendar writes. Ask: block Tuesday morning next week from 9 to 11 for deep work, no invitees. Claude should confirm the date it interpreted, create the event, and tell you the event ID. Open Google Calendar in a browser to verify the block is there. If you get a permission error, calendar.events was declined or missing from the original consent screen; re-run consent by deleting the token cache.

The third prompt tests Gmail drafts. Ask: draft an email to Alice at alice@example.com about Project Y, telling her the phase one review is rescheduled to next Thursday. Claude should produce a draft and place it in your Gmail drafts folder. Open Gmail on the web or on your phone and confirm the draft appears, addressed correctly, with a reasonable subject line. The critical check is that Claude is not sending, only drafting. If you see a sent item instead of a draft, stop and re-read the scope list; gmail.send is a different scope from gmail.compose and should only be granted if you genuinely want autonomous sending.

Running these three in order takes about two minutes and surfaces ninety per cent of configuration mistakes.

Gotchas

Three things trip founders up more than anything else.

The first is Workspace Business admin consent. If your Google account belongs to a business Workspace where the admin has restricted third-party application access, your personal OAuth client will be blocked at the consent screen with a message about your organisation's settings. The fix is for a Workspace admin to go to the Google Admin console, navigate to Security -> Access and data control -> API controls -> Manage third-party app access, and add your OAuth client ID to the trusted list. There is no way around this from the user side; the admin has to grant it. If you are the admin, take thirty seconds and do it. If you are not, send the client ID to whoever is.

The second is rate limits. Gmail's API allows 250 quota units per user per second, Drive allows around 1,000 queries per 100 seconds, and Calendar sits in between. A long Claude session that searches your entire Drive in a loop or reads dozens of threads in one turn can brush against these limits. The symptoms are usually unhelpful: an MCP tool call returns an error string that mentions 429 or quota exceeded, and Claude may retry silently and confuse itself. If you see tool calls failing mid-session while earlier ones succeeded, wait a minute and try again before assuming something is broken.

The third is token refresh. The refresh token stored locally is long-lived but not eternal. Google expires refresh tokens after six months of inactivity, after password changes, and in some tenancy changes. If tools suddenly start failing with authentication errors after a stretch of working, delete the local token cache and re-run consent. The whole re-consent takes about thirty seconds.

Where to go next

Once the three-prompt suite passes, you have a working Workspace connection and the interesting question becomes what to do with it. The obvious starter habit is to keep a Claude window open during meetings and ask it to draft the follow-up email, pulling in the relevant Drive doc and scheduling the next check-in, all in one turn. Beyond that there are MCP servers for Slack, Notion, GitHub, Linear, and most of the tools a founder touches daily. Adding them is the same pattern you just did, with a different credentials file and a new entry in the same config.json.

If the OAuth console trip sounded like a lot for something you will do once, it is, and for some founders paying someone to handle it is the right call. -> WitsCode Workspace-MCP setup is a done-in-an-hour service that hands you a working Claude Desktop with Workspace, plus a short Loom explaining exactly what to type to get value out of it in the first week.