Google Workspace MCP

Google Workspace MCP server for Claude Code and AI agents. Gmail, Drive, Sheets, Docs, Slides, Calendar, Tasks, Forms and Contacts through the official Workspace CLI, so your credential never leaves your machine.

One connection covers Gmail, Drive, Sheets, Docs, Slides, Calendar, Tasks, Forms and Contacts.

It wraps Google's own Workspace CLI, so your credential is created by you and stays on your machine.

That also sidesteps the security assessment a third-party OAuth app needs for mailbox and Drive access.

Built on Google's own Workspace CLI, so this server never handles your Google credentials.

Built by Navid Moazzez.

Contents

1. What you can ask it 💬

• What did I agree to with the agency, and is it in the calendar?

• Summarise every unread email from this week and tell me which need a reply.

• Draft replies to the three that matter. Do not send them.

• Find the pricing spreadsheet and tell me what changed since March.

• Pull every response to the onboarding form into a new sheet.

• Who did I email about the launch, and did they reply?

• Build a doc from the notes in that folder.

• What is on my calendar next week that I could move?

The first one is the point. It reads mail and calendar together, which no single Google product does for you.

2. Quick install ⚡

Node 20 or newer. Nothing else.

npx -y @thenavidm/google-workspace-mcp --version

That is the whole install. npx fetches it on demand, so there is nothing to update later.

You also need Google's Workspace CLI, which is what actually talks to Google:

# macOS
brew install googleworkspace/tap/gws

# or download a binary
# https://github.com/googleworkspace/cli/releases

3. Setup 🔑

One command, once.

gws auth login

A browser opens, you approve, and you are done. The credential belongs to the CLI, not to this server.

Limit what it can touch while you are there:

gws auth login --services drive,gmail,calendar
gws auth login --readonly

You will see an "unverified app" warning

That is expected and it is not a problem. Google shows it for any OAuth app it has not reviewed, and reviewing an app that only you use is not worth the process. Click Advanced, then Go to (your app).

If you would rather not see it, gws auth setup walks you through creating your own Google Cloud project, and then the app is yours.

Revoking

gws auth logout

Or remove access at myaccount.google.com/permissions.

4. Connect your client 🔌

Claude Code

claude mcp add google-workspace -- npx -y @thenavidm/google-workspace-mcp@latest

--scope user makes it available in every project rather than the current one.

Claude Desktop

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@thenavidm/google-workspace-mcp@latest"]
    }
  }
}

Tip Claude Desktop does not inherit your shell PATH, so it may not find npx or gws. If it fails, use absolute paths from which npx and which gws, and set GWS_BIN to the second one.

Quit Claude Desktop completely and reopen it.

claude.ai on the web

claude.ai runs connectors from Anthropic's cloud, not from your machine, so it cannot launch a local command. It needs this server running somewhere with a public HTTPS address. See section 7.

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@thenavidm/google-workspace-mcp@latest"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json, same shape as Cursor.

VS Code

.vscode/mcp.json. The key is servers, not mcpServers.

{
  "servers": {
    "google-workspace": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/google-workspace-mcp@latest"]
    }
  }
}

Codex CLI

~/.codex/config.toml

[mcp_servers.google-workspace]
command = "npx"
args = ["-y", "@thenavidm/google-workspace-mcp@latest"]

Everything else

Any stdio MCP client takes the same two things: the command npx and those arguments.

5. Check it worked 🩺

npx -y @thenavidm/google-workspace-mcp doctor

It checks the CLI is present, that you are authenticated, and makes one live API call. If every line is fine, restart your client and ask it what is on my calendar today.

6. Tools 🛠️

38 tools. The named ones cover what an assistant reaches for; workspace_raw covers the rest.

Gmail

Drive

Sheets, Docs, Slides

sheets_read · sheets_write · sheets_append · sheets_get · sheets_create docs_get · docs_create · docs_append slides_get · slides_create

Calendar and Tasks

calendar_list_events · calendar_create_event · calendar_update_event · calendar_delete_event · calendar_list_calendars tasks_lists · tasks_list · tasks_create · tasks_complete

Forms and Contacts

forms_get · forms_responses · contacts_search · contacts_list

Everything else

Read the schema before using workspace_raw, rather than guessing field names.

7. Running it on a server 🖥️

Needed for claude.ai, and useful if you want it always on.

curl -fsSL https://raw.githubusercontent.com/thenavidm/google-workspace-mcp/main/deploy/install.sh | sudo bash

That creates a dedicated user, installs the gws binary with its checksum verified, generates a bearer token, and runs a systemd service bound to 127.0.0.1:8787. Nothing is exposed to the internet by the script: put it behind your existing reverse proxy, which is where TLS belongs.

Then authenticate as the service user. The script prints the exact command.

Docker instead:

docker build -t google-workspace-mcp .
docker run -d --name gws-mcp -p 127.0.0.1:8787:8787 \
  -e GWS_MCP_TOKEN="$(openssl rand -hex 32)" \
  -v ~/.config/gws:/home/node/.config/gws \
  google-workspace-mcp

The config mount must be read-write: gws stores its encryption key and cached discovery documents there, not just a token.

Note On macOS the credential lives in the OS keyring, so copying ~/.config/gws to a Linux box does not work. Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file and authenticate on the server itself.

8. Safety 🛡️

Email is drafted, never sent silently. gmail_create_draft writes to Drafts and stops. Sending is a separate tool needing confirm: true, because a sent email cannot be recalled.

Nothing is deleted permanently. drive_trash is recoverable for 30 days. There is no hard-delete tool.

Turn writes off, or narrow the surface:

GWS_READ_ONLY=1                  # refuse every write
GWS_SERVICES=drive,calendar      # nothing else is even registered

GWS_SERVICES removes the other tools from the list rather than failing when called. A model cannot reach for a tool it cannot see.

Prompt injection. Anything read from a mailbox or a shared document was written by someone else and can contain text shaped like an instruction. The server tells the model to treat it as data. That helps and is not a guarantee: for an agent working unattended on other people's content, GWS_READ_ONLY=1 is the real defence.

Full detail in SECURITY.md.

9. Troubleshooting 🔧

Run doctor first. It answers most of it.

10. FAQ ❓

An MCP server is a standard way to give an AI assistant real access to a tool, so it can act rather than guess. You install it once, your assistant gains a set of tools, and the same server works in Claude, Cursor, ChatGPT and anything else that speaks MCP.

Without one, an assistant can only talk about your email. With one, it can read it.

Google's suite of work apps: Gmail, Drive, Docs, Sheets, Slides, Calendar, Tasks, Forms and Contacts. If you use a Gmail address, you already have it.

You need to be comfortable running two commands in a terminal: one to install, one to sign in. After that it is all conversation with your assistant.

If a terminal is unfamiliar, the Claude Desktop path in section 4 is the shortest route.

Your Google data goes from Google to the machine running this server, and from there to whichever AI client you connected. It does not pass through any server of ours, because there isn't one.

The exception is deliberate and worth understanding: whatever your assistant reads, it sends to its own model provider, the same as anything else you paste into a chat.

Work across apps in one step. Gmail cannot search your Drive, and Calendar cannot read your mail. An assistant with this server does both in a single question, and it can act on the answer: draft the reply, create the event, update the sheet.

It can trash a Drive file and delete a calendar event, and both need confirm: true set deliberately. Trashed files are recoverable for 30 days. There is no permanent-delete tool.

It cannot send an email by accident: drafting and sending are separate tools, and sending needs confirmation.

If you want none of that, run it with GWS_READ_ONLY=1.

It costs nothing. The server is free and open source, Google's CLI is free, and the Workspace APIs are free at any volume a person generates.

It works with any MCP client. Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI and Gemini CLI all run it locally.

claude.ai is the exception: it connects from Anthropic's cloud rather than your machine, so it needs the server running somewhere with a public HTTPS address. See section 7.

One account per server. The gws CLI holds a single login.

For a second account, run a second copy with GOOGLE_WORKSPACE_CLI_CONFIG_DIR pointing somewhere else, and add it to your client under a different name.

It refreshes itself. The CLI holds a refresh token and renews access silently, so you sign in once.

If you ever do need to sign in again, doctor says so plainly rather than failing with a permissions error.

Questions

Run into a problem or have a question? Open an issue and I will help.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This Google Workspace MCP server is one piece of that system.

Links

• Personal website: navid.me

• Navid Media: navid.media

• YouTube: @thenavidm and @thenavidai

• X: @thenavidm

• Instagram: @thenavidm

• LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

License

MIT. Free to use, modify, and share.

Not affiliated with, endorsed by, or sponsored by Google LLC. Google Workspace, Gmail, Google Drive, Google Docs, Google Sheets, Google Slides, Google Calendar, Google Tasks, Google Forms and Google Contacts are trademarks of Google LLC. This project wraps the official Google Workspace CLI and holds no credentials of its own.

© 2026 NM Media. Made with ❤️ by Navid Moazzez.