How to Use the Google Workspace MCP Server with Claude Code and Codex

Connect Your AI Coding Agents to Gmail, Drive, and Calendar

If you’ve been using Claude Code or OpenAI Codex to write and run code, you’ve probably hit the same wall: the agents are good at reasoning and writing, but they’re isolated from the tools your work actually lives in. They can’t check your inbox, create a calendar event, or pull a spec doc from Drive without you copying and pasting everything manually.

The Google Workspace MCP server changes that. It gives your AI coding agents direct, authorized access to Gmail, Google Drive, Google Calendar, Google Docs, Sheets, and Chat — so they can read, write, and act across your workspace as part of an automated workflow.

This guide covers how the Google Workspace MCP server works, how to set it up with Claude Code and Codex, what you can realistically automate, and where things tend to go wrong.

---

What the Google Workspace MCP Server Actually Does

MCP stands for Model Context Protocol — an open standard originally developed by Anthropic to give AI models a consistent way to call external tools and services. Think of it as a structured interface between an AI agent and the outside world.

An MCP server exposes a set of “tools” the agent can call. When you run the Google Workspace MCP server, it registers tools like gmail_search, drive_list_files, calendar_create_event, and docs_get_content. The agent — whether that’s Claude Code, Codex, or something else — can then call those tools during a session, just like it would call a function.

The key distinction from simpler integrations: MCP connections are stateful, typed, and designed for agentic use. The agent doesn’t just get a blob of data dumped into its context. It can query, filter, and act iteratively — the same way a human would navigate a tool.

What Services Are Supported

The official Google Workspace MCP server (maintained by Google) covers:

• Gmail — search messages, read full email threads, send emails, manage labels
• Google Drive — list and search files, read document content, create and update files
• Google Calendar — list calendars, read and create events, check availability
• Google Docs — read and write document content
• Google Sheets — read and write spreadsheet data
• Google Chat — send messages to spaces and direct messages

Coverage varies slightly depending on which version of the server you’re running, so check the release notes when you install.

---

Prerequisites Before You Start

Before you configure anything, you need three things in place.

A Google Cloud Project with OAuth Credentials

The MCP server authenticates via OAuth 2.0 using your own Google Cloud project. You’re not using a shared API key — you’re authorizing access on behalf of a specific Google account.

To set this up:

1. Go to the Google Cloud Console and create a new project (or use an existing one).
2. Enable the APIs you need: Gmail API, Google Drive API, Google Calendar API, and any others.
3. Under APIs & Services > Credentials, create an OAuth 2.0 Client ID. Select “Desktop app” as the application type.
4. Download the credentials.json file. You’ll need this during server setup.

Node.js 18 or Later

The MCP server is a Node.js package. Make sure you have Node 18+ installed. You can verify with node --version.

Claude Code or Codex CLI Installed

• Claude Code: Anthropic’s agentic coding environment. Install via npm install -g @anthropic-ai/claude-code or follow the official setup instructions.
• OpenAI Codex: OpenAI’s agent (the CLI version). Install via npm install -g @openai/codex.

Both support MCP out of the box.

---

Setting Up the Google Workspace MCP Server

Step 1: Install the MCP Server Package

Run this in your terminal:

npm install -g @google/mcp-server-workspace

Or if you prefer to run it without a global install:

npx @google/mcp-server-workspace

Step 2: Authenticate with Your Google Account

Place your downloaded credentials.json in a directory the server can access — by convention, ~/.config/google-workspace-mcp/credentials.json works well.

Then run the authentication flow:

mcp-server-workspace auth

This opens a browser window asking you to sign in with Google and grant the requested permissions. Once you approve, the server saves a token.json locally. This token refreshes automatically as long as you’ve granted offline access.

If you’re setting this up in a headless or CI environment, you’ll need to handle the OAuth flow differently — typically by running the auth step locally first and copying the token file over.

Step 3: Configure the Server in Claude Code

Claude Code reads MCP server configurations from a settings file. Open or create ~/.claude/settings.json and add the following:

{
  "mcpServers": {
    "google-workspace": {
      "command": "mcp-server-workspace",
      "args": (),
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/Users/yourname/.config/google-workspace-mcp/credentials.json",
        "GOOGLE_TOKEN_PATH": "/Users/yourname/.config/google-workspace-mcp/token.json"
      }
    }
  }
}

Adjust the paths to match your actual file locations. The command value should point to wherever the binary was installed — run which mcp-server-workspace if you’re unsure.

Restart Claude Code after saving. You can verify the server loaded correctly by asking Claude Code to list available tools — it should show the Google Workspace tool set.

Step 4: Configure the Server in Codex

Codex uses a similar MCP configuration format. Add an mcp_servers block to your ~/.codex/config.yaml:

mcp_servers:
  google-workspace:
    command: mcp-server-workspace
    env:
      GOOGLE_CREDENTIALS_PATH: /Users/yourname/.config/google-workspace-mcp/credentials.json
      GOOGLE_TOKEN_PATH: /Users/yourname/.config/google-workspace-mcp/token.json

Save and restart Codex. The agent will pick up the configuration on the next session start.

---

What You Can Actually Automate

With the server running, both Claude Code and Codex can now use Google Workspace as part of their reasoning and execution loop. Here are some concrete things that become possible.

Automate Code Documentation from Drive Specs

Tell Claude Code: “Read the product spec in Drive called ‘Auth Service v2’ and generate the OpenAPI schema for it.”

Claude Code will call drive_search to find the file, docs_get_content to read it, then generate the schema directly — no copy-pasting required.

Summarize Email Threads into Action Items

Ask Claude Code or Codex: “Check my Gmail for any unread threads tagged ‘bug report’ from the last 48 hours and write a markdown summary of what needs fixing.”

The agent searches Gmail, reads relevant threads, and outputs a structured list. You can go further and have it create GitHub issues or update a Notion doc with the results.

Build and Send Reports Automatically

An agent can query a Google Sheet for data, run analysis on it, format the output, and send it as an email — all in one session. For example: “Read the Q3 sales data from the ‘Revenue Tracker’ spreadsheet and email a summary to the team distribution list.”

Manage Calendar Events from Code Context

If you’re automating project workflows, the agent can create calendar events based on task deadlines, check for scheduling conflicts, or look up upcoming meetings before sending a status update. “Schedule a 30-minute review meeting next Tuesday afternoon and invite the addresses in the REVIEWERS variable.”

Cross-Reference Documentation and Code

Point the agent at a Drive folder containing architecture docs and ask it to check whether the current codebase matches the spec. The agent reads the docs, reads the code, and surfaces discrepancies.

---

Common Setup Problems and How to Fix Them

The Server Isn’t Showing Up in Claude Code

Check three things in order:

1. The path in settings.json is correct and the binary is actually at that location.
2. You have read permission on both the credentials.json and token.json files.
3. You restarted Claude Code after editing the config.

You can test the server independently by running mcp-server-workspace in your terminal. If it throws an error, fix that before debugging the Claude Code integration.

OAuth Scope Errors

If a tool call fails with a “Request had insufficient authentication scopes” error, the token you generated doesn’t include the permission for that service. You’ll need to re-run mcp-server-workspace auth and make sure the required APIs are enabled in your Google Cloud project.

Token Expiry in Long-Running Sessions

OAuth tokens for desktop apps expire and need to be refreshed. The server handles this automatically if you granted offline access during authentication. If you didn’t, delete token.json and run the auth flow again — this time, look for the “offline access” or “grant access to refresh tokens” option in the consent screen.

Codex Not Recognizing YAML Config

Codex is sensitive to YAML indentation. Make sure there are no tab characters in your config.yaml — use spaces only. Also double-check that the command resolves correctly in your shell’s PATH.

---

Where MindStudio Fits

The Google Workspace MCP server is excellent for giving coding agents ad-hoc access to Workspace during a session. But if you want persistent, scheduled, or event-triggered automation — workflows that run without a developer in the loop — that’s where MindStudio fills the gap.

MindStudio is a no-code platform for building AI agents that connect directly to Google Workspace and 1,000+ other tools. You can build agents that monitor a Gmail inbox and trigger actions when specific emails arrive, pull from Drive on a schedule, update Sheets based on external events, or route Calendar data into downstream systems — all without managing MCP servers or OAuth flows yourself.

The practical difference: Claude Code with the Google Workspace MCP server is a developer tool for interactive sessions. MindStudio is for production workflows that run autonomously, around the clock, without someone at a terminal.

If you’re building something that needs to run every morning, fire on a webhook, or respond to an email — MindStudio’s Google Workspace integrations are worth looking at. You can connect Gmail, Drive, Calendar, Docs, and Sheets in a visual workflow builder, chain AI reasoning steps in between, and deploy it in under an hour.

MindStudio is free to start at mindstudio.ai.

For teams that want to go further — exposing MindStudio agents as MCP servers themselves so tools like Claude Code can call them — MindStudio supports that too through its agentic MCP server capability.

---

Practical Tips for Getting the Most Out of This Setup

Be specific in your prompts. When you ask Claude Code or Codex to interact with Workspace, the more precise your instructions, the better. “Check Gmail” is vague. “Search Gmail for unread messages with subject containing ‘deploy’ sent in the last 24 hours” gives the agent a clear query to execute.

Use scoped permissions. When setting up your Google Cloud project, only enable the APIs you actually need. This reduces your attack surface and makes the OAuth consent screen simpler.

Store credentials outside your project directory. Don’t commit credentials.json or token.json to a repo. Keep them in a home directory config folder and reference them via environment variables.

Test tools individually before building complex workflows. Ask the agent to do one thing — “read this email” — before chaining five operations together. This makes it easier to spot where things break.

Check rate limits. The Gmail and Drive APIs have per-minute quotas. If you’re running the agent against large datasets or many requests in a short window, you may hit limits. The MCP server will surface these as errors; plan accordingly.

---

FAQ

What is the Google Workspace MCP server?

The Google Workspace MCP server is a Model Context Protocol server that exposes Gmail, Google Drive, Google Calendar, Google Docs, Google Sheets, and Google Chat as callable tools for AI agents. It lets agents like Claude Code and Codex read, write, and act on your Workspace data as part of a session.

Does the Google Workspace MCP server work with Claude Desktop as well?

Yes. The same configuration format works for Claude Desktop — you add the server to claude_desktop_config.json under mcpServers. The setup is nearly identical to Claude Code, and the same OAuth credentials apply.

Is the Google Workspace MCP server official or third-party?

Google maintains an official MCP server for Workspace, available as an npm package. There are also community-built alternatives, but the official version is the most complete and best supported.

Do I need a paid Google Workspace account to use this?

No. The MCP server works with standard personal Google accounts (gmail.com) as well as Google Workspace (formerly G Suite) accounts. The key requirement is a Google Cloud project with OAuth credentials, which is free to create.

Can Claude Code or Codex write back to Google Drive, or is it read-only?

Both read and write operations are supported, depending on the tool and the scopes you’ve granted. You can create files, update Docs and Sheets, send emails, and create calendar events — not just read data. Make sure the relevant write scopes are included when you authorize.

What’s the difference between using MCP and using the Google Workspace API directly?

Using the API directly requires writing code to handle authentication, request formatting, pagination, and error handling. The MCP server abstracts all of that. The agent calls a typed tool with clear parameters and gets back structured output — it doesn’t need to know the API surface or manage HTTP requests.

---

Key Takeaways

• The Google Workspace MCP server gives Claude Code and Codex direct access to Gmail, Drive, Calendar, Docs, Sheets, and Chat through a typed tool interface.
• Setup requires a Google Cloud project, OAuth credentials, Node.js 18+, and configuration in your agent’s settings file.
• Common issues involve OAuth scope mismatches, path configuration errors, and token expiry — all fixable with the troubleshooting steps above.
• The setup works well for interactive, developer-driven sessions; for persistent, scheduled, or trigger-based automation, a platform like MindStudio is better suited.
• Be specific with prompts, scope your permissions carefully, and test individual tool calls before chaining complex workflows.

If you want to build AI agents that interact with Google Workspace without managing MCP infrastructure yourself, MindStudio has pre-built Google Workspace integrations ready to use in a visual workflow builder — free to try, no code required.