Google Workspace MCP Server & CLI

A free, open source Google Workspace MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents work across Gmail, Drive, Sheets, Docs, Calendar and more.

Star on GitHub

npm

by Navid Moazzez·Updated 30 sep. 2026·9 min read

~/google-workspace-mcp-cli

$ claude

Claude Code v2.1.220

MCP CLI

Your computer

macOS Windows Linux

Install the CLI. It needs Node 20 or newer.

npm install -g @thenavidm/google-workspace-mcp-cli

2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
```
mkdir -p ~/.claude/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.claude/skills/google-workspace/
```
3
Check your setup.
It names anything that's wrong and the fix.
```
google-workspace-cli doctor
```
4
Ask Claude Code to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Claude Code finds the one it needs.

Needs Node 20 or newer and Google's Workspace CLI, signed in once. Set it up.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Google Workspace MCP server and CLI gives your AI real access to Gmail, Drive, Sheets, Docs, Slides, Calendar, Tasks, Forms and Contacts. It works through Google's own Workspace CLI, so your credential is created by you and never leaves your computer.

It's one install with 2 ways in. Claude, Codex, Cursor or any other MCP app calls its 38 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

Here's what the Google Workspace MCP server and CLI is, how to set it up in each app, and every tool it has.

What is the Google Workspace MCP server & CLI?

The Google Workspace MCP server & CLI is a free, open source program that lets AI agents work across Gmail, Drive, Sheets, Docs, Calendar and the rest of Google Workspace for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call through Google's official Workspace CLI, gws.

The CLI is the same program as commands. google-workspace-cli calendar-list-events runs the same code your AI runs when you ask what's on your calendar, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
What did I agree to with the agency, and is it in the calendar?
Summarize every unread email from this week and tell me which need a reply.
Draft replies to the three that matter. Don't send them.
Find the pricing spreadsheet and tell me what changed since March.
Pull every response to the onboarding form into a new sheet.
What's on my calendar next week that I could move?

The first one shows why this is useful. It reads your mail and your calendar together, which no single Google product does for you.

How to install the Google Workspace MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, after you install Google's Workspace CLI and sign in to it once.

Before you start0/2

You have Node 20 or newer on your computer.

You have Google's Workspace CLI, gws, which the next section installs.

Pro tip: Your Google credential belongs to gws, not to this server. That also sidesteps the security review a third-party app needs for mailbox and Drive access.

Set up Google Workspace

The server talks to Google through gws, Google's own Workspace CLI, so the only setup is installing it and signing in once.

Install gws and sign in0/3

1Install it: on a Mac, brew install googleworkspace/tap/gws. Other systems download a binary from its releases.

2Run gws auth login.

3Approve in the browser that opens.

To limit what it can touch, sign in with gws auth login --services drive,gmail,calendar, or gws auth login --readonly.

Google shows an "unverified app" warning for any app it hasn't reviewed. Click Advanced, then Go to your app. If you'd rather not see it, gws auth setup walks you through a Google Cloud project of your own.

Check that it works

Run the doctor. It checks that gws is installed and signed in, and makes a live Drive call.

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

"Not authenticated" means run gws auth login on the computer running the server.

Use the Google Workspace CLI

The CLI is the same 38 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so gmail_search runs as google-workspace-cli gmail-search.

npm install -g @thenavidm/google-workspace-mcp-cli
google-workspace-cli
google-workspace-cli gmail-search --q "is:unread newer_than:2d" --max 5
google-workspace-cli calendar-list-events
google-workspace-cli drive-search --q "name contains 'invoice'"

The bare google-workspace-cli lists every command, and google-workspace-cli <command> --help shows what a command takes. Sending a draft, trashing a file, deleting an event and the raw API tool ask for --confirm first, like they do for your AI.

These flags work on every command:

Flag	What it does
`--json`	Prints JSON
`--compact`	Prints the JSON on one line
`--agent`	Machine mode: JSON, compact, no prompts and no color
`--select a,b.c`	Keeps only those fields, and a dotted path goes deeper
`--confirm`	Lets a write that asks first go ahead

A script can branch on the exit code:

Exit code	What it means
0	It worked
2	The command was typed wrong, or a write needed `--confirm`
3	It wasn't found
4	Google Workspace rejected the credentials
5	Google Workspace's API failed
7	You hit a rate limit, so wait and try again
10	Nothing is set up yet

MCP server or CLI: which one?

Both are the same program with the same 38 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool

MCP server: 6,700 tokens
CLI: Nothing

Every message, in Claude Code

MCP server: 810 tokens
CLI: Nothing

When Google Workspace comes up

MCP server: Nothing more, or in Claude Code the tools it picks
CLI: 1,800 tokens, once

20 messages with Google Workspace in 1, every tool loaded

MCP server: 134,000 tokens
CLI: 1,800 tokens

Works in Claude Desktop's chat

MCP server: Yes
CLI: No, there's no terminal there

Works in a script, a cron job or CI

MCP server: No
CLI: Yes

What it costs	MCP server	CLI
Every message, in an app that loads every tool	6,700 tokens	Nothing
Every message, in Claude Code	810 tokens	Nothing
When Google Workspace comes up	Nothing more, or in Claude Code the tools it picks	1,800 tokens, once
20 messages with Google Workspace in 1, every tool loaded	134,000 tokens	1,800 tokens
Works in Claude Desktop's chat	Yes	No, there's no terminal there
Works in a script, a cron job or CI	No	Yes

An app that loads every tool up front sends the full list with every message, whether you mention Google Workspace or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Google Workspace comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 140 tokens.

When the whole conversation is about Google Workspace, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using it, with your AI app's own switch. GWS_SERVICES=gmail,calendar registers only the services you name, and the rest cost nothing.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

Email is drafted, not sent

gmail_create_draft writes to your Drafts folder and stops, so you can read it before anything goes out. Sending is a separate tool, gmail_send_draft, and it asks for a confirm check first, because a sent email can't be recalled.

Nothing is deleted for good either. drive_trash moves a file to the trash, where it stays recoverable for 30 days, and there is no hard delete.

Reach anything else

The named tools cover what people ask for most. workspace_raw reaches the roughly 400 other Workspace API methods, and workspace_schema shows the exact fields one of them takes, so your AI never has to guess them.

Every Google Workspace tool

All 38 tools, grouped the way the repo groups them. 20 only read, and 18 change something in your Google account.

Gmail

gmail_search

What it does: Search the mailbox with Gmail's own query syntax (from:, to:, subject:, has:attachment, newer_than:7d, is:unread).
Kind: Reads

gmail_get_message

What it does: One message in full, including the body and headers.
Kind: Reads

gmail_get_thread

What it does: A whole conversation in order.
Kind: Reads

gmail_create_draft

What it does: Write a draft.
Kind: Writes

gmail_send_draft

What it does: Send a draft that already exists.
Kind: Asks first

gmail_modify_labels

What it does: Add or remove labels on a message.
Kind: Writes

gmail_list_labels

What it does: Every label with its id.
Kind: Reads

Tool	What it does	Kind
`gmail_search`	Search the mailbox with Gmail's own query syntax (from:, to:, subject:, has:attachment, newer_than:7d, is:unread).	Reads
`gmail_get_message`	One message in full, including the body and headers.	Reads
`gmail_get_thread`	A whole conversation in order.	Reads
`gmail_create_draft`	Write a draft.	Writes
`gmail_send_draft`	Send a draft that already exists.	Asks first
`gmail_modify_labels`	Add or remove labels on a message.	Writes
`gmail_list_labels`	Every label with its id.	Reads

Calendar

calendar_list_events

What it does: Events in a window.
Kind: Reads

calendar_create_event

What it does: Create an event.
Kind: Writes

calendar_update_event

What it does: Change an existing event.
Kind: Writes

calendar_delete_event

What it does: Delete an event.
Kind: Asks first

calendar_list_calendars

What it does: Every calendar this account can see, with its id.
Kind: Reads

Tool	What it does	Kind
`calendar_list_events`	Events in a window.	Reads
`calendar_create_event`	Create an event.	Writes
`calendar_update_event`	Change an existing event.	Writes
`calendar_delete_event`	Delete an event.	Asks first
`calendar_list_calendars`	Every calendar this account can see, with its id.	Reads

Drive

drive_search

What it does: Find files with Drive query syntax (name contains 'x', mimeType='application/pdf', modifiedTime > '2026-01-01').
Kind: Reads

drive_get_file

What it does: Metadata for one file: name, type, size, owners, sharing and link.
Kind: Reads

drive_export

What it does: Read the CONTENT of a Google Doc, Sheet or Slide as text.
Kind: Reads

drive_create_folder

What it does: Create a folder, optionally inside another.
Kind: Writes

drive_share

What it does: Grant someone access to a file.
Kind: Writes

drive_trash

What it does: Move a file to the trash.
Kind: Asks first

Tool	What it does	Kind
`drive_search`	Find files with Drive query syntax (name contains 'x', mimeType='application/pdf', modifiedTime > '2026-01-01').	Reads
`drive_get_file`	Metadata for one file: name, type, size, owners, sharing and link.	Reads
`drive_export`	Read the CONTENT of a Google Doc, Sheet or Slide as text.	Reads
`drive_create_folder`	Create a folder, optionally inside another.	Writes
`drive_share`	Grant someone access to a file.	Writes
`drive_trash`	Move a file to the trash.	Asks first

Sheets

sheets_read

What it does: Read a cell range, e.g.
Kind: Reads

sheets_write

What it does: Overwrite a range with new values.
Kind: Writes

sheets_append

What it does: Add rows to the end of a sheet without touching what is there.
Kind: Writes

sheets_get

What it does: Spreadsheet structure: every sheet name, id, and dimensions.
Kind: Reads

sheets_create

What it does: Create a new spreadsheet and return its id.
Kind: Writes

Tool	What it does	Kind
`sheets_read`	Read a cell range, e.g.	Reads
`sheets_write`	Overwrite a range with new values.	Writes
`sheets_append`	Add rows to the end of a sheet without touching what is there.	Writes
`sheets_get`	Spreadsheet structure: every sheet name, id, and dimensions.	Reads
`sheets_create`	Create a new spreadsheet and return its id.	Writes

Docs

docs_get

What it does: Read a Google Doc's full structured content.
Kind: Reads

docs_create

What it does: Create a new Google Doc with a title, and optionally an opening body of text.
Kind: Writes

docs_append

What it does: Add text to the end of a Doc without touching what is already there.
Kind: Writes

Tool	What it does	Kind
`docs_get`	Read a Google Doc's full structured content.	Reads
`docs_create`	Create a new Google Doc with a title, and optionally an opening body of text.	Writes
`docs_append`	Add text to the end of a Doc without touching what is already there.	Writes

Slides

slides_get

What it does: A presentation's structure and the text on every slide.
Kind: Reads

slides_create

What it does: Create an empty presentation and return its id.
Kind: Writes

Tool	What it does	Kind
`slides_get`	A presentation's structure and the text on every slide.	Reads
`slides_create`	Create an empty presentation and return its id.	Writes

Tasks

tasks_lists

What it does: Every task list with its id.
Kind: Reads

tasks_list

What it does: Tasks in a list.
Kind: Reads

tasks_create

What it does: Add a task.
Kind: Writes

tasks_complete

What it does: Mark a task done.
Kind: Writes

Tool	What it does	Kind
`tasks_lists`	Every task list with its id.	Reads
`tasks_list`	Tasks in a list.	Reads
`tasks_create`	Add a task.	Writes
`tasks_complete`	Mark a task done.	Writes

Forms

forms_get

What it does: A form's questions and settings.
Kind: Reads

forms_responses

What it does: Every response to a form.
Kind: Reads

Tool	What it does	Kind
`forms_get`	A form's questions and settings.	Reads
`forms_responses`	Every response to a form.	Reads

Contacts

contacts_search

What it does: Search your own contacts by name, email or company.
Kind: Reads

contacts_list

What it does: All your contacts, paged.
Kind: Reads

Tool	What it does	Kind
`contacts_search`	Search your own contacts by name, email or company.	Reads
`contacts_list`	All your contacts, paged.	Reads

Everything else

workspace_raw

What it does: Call any Google Workspace API method the curated tools do not cover.
Kind: Asks first

workspace_schema

What it does: The exact parameters and request body a method expects, straight from Google's discovery service.
Kind: Reads

Tool	What it does	Kind
`workspace_raw`	Call any Google Workspace API method the curated tools do not cover.	Asks first
`workspace_schema`	The exact parameters and request body a method expects, straight from Google's discovery service.	Reads

Is the Google Workspace MCP server safe?

Writes work from the start, because drafting, filing and scheduling are the point of the tool. The ones that can't be undone ask first.

gmail_send_draft, drive_trash, calendar_delete_event and workspace_raw ask for a confirm check first, marked Asks first in the tool tables above.

Make it read-only

Set GWS_READ_ONLY=1 and every write is refused. GWS_SERVICES=drive,calendar goes further: the other services aren't even registered, so your AI can't reach for them.

⚠️

Watch out: 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 your AI to treat it as data, but for an agent working on its own, GWS_READ_ONLY=1 is the real defense.

Your data

There's no server of ours in between. Your Google data goes from Google to your computer, and from there to the AI app you connected.

Your credential stays with gws, and this server never sees or stores it. Whatever your AI reads, it sends to its own model provider, the same as anything you paste into a chat.

Google Workspace MCP server settings

Every setting is an environment variable in your app's config. None of them are required.

GWS_BIN

Default: gws on your PATH
What it does: Points at the gws binary, when your app can't find it

GWS_READ_ONLY

Default: off
What it does: 1 refuses every write

GWS_SERVICES

Default: all
What it does: Registers only these services, for example drive,gmail,calendar

GWS_MCP_TOKEN

Default: none
What it does: Sets the bearer token, which --http requires

Variable	Default	What it does
`GWS_BIN`	`gws` on your PATH	Points at the gws binary, when your app can't find it
`GWS_READ_ONLY`	off	`1` refuses every write
`GWS_SERVICES`	all	Registers only these services, for example `drive,gmail,calendar`
`GWS_MCP_TOKEN`	none	Sets the bearer token, which `--http` requires

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

What you see	What to do
"The gws CLI was not found"	Install it, or set `GWS_BIN` to its full path
"Not authenticated"	Run `gws auth login` on the computer running the server
It works in a terminal, not in Claude Desktop	Claude Desktop doesn't read your shell's PATH, so use full paths
An "unverified app" warning	That's expected. Click Advanced, then Go to your app
A tool says its service is disabled	`GWS_SERVICES` is set and leaves that service out

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free tools for your work

Turn a doc into a presentation, or make a QR code for a meeting link.

Presentation generator QR code generator

Google Workspace MCP Server FAQs

Here are the questions people ask most about the Google Workspace MCP server and CLI.

What is the Google Workspace MCP server & CLI?

The Google Workspace MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor work across Gmail, Drive, Sheets, Docs, Calendar and the rest of Google Workspace.

It has 38 tools for Gmail, Drive, Sheets, Docs, Slides, Calendar, Tasks, Forms and Contacts, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

What is an MCP server?

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

What is the Google Workspace CLI?

The Google Workspace CLI is the same program as the Google Workspace MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

Should I use the Google Workspace MCP server or the CLI?

Use the Google Workspace MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Is the Google Workspace MCP server free?

Yes, the Google Workspace MCP server is free and open source under the MIT license, Google's Workspace CLI is free, and the Workspace APIs cost nothing at the volume a person uses.

The only thing you pay for is your own AI app.

Can the Google Workspace MCP server send email without me?

No, the Google Workspace MCP server drafts email and stops.

Sending is a separate tool that asks for a confirm check first, because a sent email can't be recalled.

Does the Google Workspace MCP server see my Google password?

No, your credential belongs to Google's Workspace CLI, and the server never sees or stores it.

Signing in happens in your own browser.

Can I connect more than one Google account?

Yes, run a second copy with GOOGLE_WORKSPACE_CLI_CONFIG_DIR pointing at another folder.

Add it to your app under a different name.

Can the Google Workspace MCP server delete my files?

No, drive_trash moves a file to the trash, where it stays recoverable for 30 days, and there is no hard delete.

Trashing asks for a confirm check first.

Which AI apps does the Google Workspace MCP server work with?

The Google Workspace MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

Who built the Google Workspace MCP server?

Navid Moazzez built the Google Workspace MCP server and maintains it.

The code is on GitHub under the MIT license, and the package is on npm.

Navid Moazzez

AI business strategist & AI OS builder

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Learn more.

More MCP servers & CLIs

View all

Google Search Console MCP server & CLI

Read your search traffic, check indexing and submit sitemaps from Claude, Codex or Cursor.

SEO

Google Search Console

iMessage MCP server & CLI

Catch up, search your history and send iMessages from Claude, Codex or Cursor, on your Mac.

Messaging

iMessage

Bluesky MCP server & CLI

Post, read and search Bluesky from Claude, Codex or Cursor, or from your terminal.

Social media

Bluesky

Substack MCP server & CLI

Draft posts, publish Notes and check your stats on Substack from Claude, Codex or Cursor.

Newsletters

Substack

Threads MCP server & CLI

Post, reply and read your insights on Threads from Claude, Codex or Cursor.

Social media

Threads

Mastodon MCP server & CLI

Post, edit and read your timelines on any Mastodon instance from Claude, Codex or Cursor.

Social media

Mastodon

TikTok MCP server & CLI

Rank your videos, read your stats and publish to TikTok from Claude, Codex or Cursor.

Social media

TikTok

ThriveCart MCP server & CLI

Check revenue, customers, subscriptions and affiliates in ThriveCart from Claude, Codex or Cursor.

Sales

ThriveCart

WordPress MCP server & CLI

Edit posts, pages, Elementor and Rank Math SEO on WordPress from Claude, Codex or Cursor.

Blogs

WordPress

Midjourney MCP server & CLI

Generate images, follow jobs and download the files from Midjourney with Claude, Codex or Cursor.

AI images

Midjourney

Google Photos MCP server & CLI

Pick photos, build albums and upload to Google Photos from Claude, Codex or Cursor.

Photos

Google Photos

Apple Photos MCP server & CLI

Search, look at and organize your Apple Photos library from Claude, Codex or Cursor, on your Mac.

Photos

Apple Photos

Apple Podcasts MCP server & CLI

Track chart ranks, read reviews and search your podcast library from Claude, Codex or Cursor.

Podcasts

Apple Podcasts

Podcast Index MCP server & CLI

Search 4 million podcasts and read episode transcripts from Claude, Codex or Cursor.

Podcasts

Podcast Index

Facebook Ad Library MCP server & CLI

Research the ads any brand runs on Facebook and Instagram, from Claude, Codex or Cursor.

Research

Facebook

Vimeo MCP server & CLI

Read transcripts, file videos into folders and add chapters from Claude, Codex or Cursor.

Video

Vimeo

YouTube MCP server & CLI

Read any video's transcript, research channels and manage your own from Claude, Codex or Cursor.

Video

YouTube

Telegram MCP server & CLI

Catch up, search years of chats and reply on Telegram from Claude, Codex or Cursor.

Messaging

OP3 MCP server & CLI

Read your podcast's downloads, real listeners and retention from Claude, Codex or Cursor.

Podcasts

OP3

Google Workspace MCP Server & CLI

Install the CLI. It needs Node 20 or newer.

Give Claude Code the skill, so it knows every command.

Check your setup.

Ask Claude Code to use google-workspace-cli.

What is the Google Workspace MCP server & CLI?

What can you ask it?

How to install the Google Workspace MCP server

Set up Google Workspace

Check that it works

Use the Google Workspace CLI

MCP server or CLI: which one?

How to spend less

Email is drafted, not sent

Reach anything else

Every Google Workspace tool

Gmail

Calendar

Drive

Sheets

Docs

Slides

Tasks

Forms

Contacts

Everything else

Is the Google Workspace MCP server safe?

Make it read-only

Your data

Google Workspace MCP server settings

Troubleshooting

Google Workspace MCP Server FAQs

More MCP servers & CLIs

Google Search Console MCP server & CLI

iMessage MCP server & CLI

Bluesky MCP server & CLI

Substack MCP server & CLI

Threads MCP server & CLI

Mastodon MCP server & CLI

TikTok MCP server & CLI

ThriveCart MCP server & CLI

WordPress MCP server & CLI

Midjourney MCP server & CLI

Google Photos MCP server & CLI

Apple Photos MCP server & CLI

Apple Podcasts MCP server & CLI

Podcast Index MCP server & CLI

Facebook Ad Library MCP server & CLI

Vimeo MCP server & CLI

YouTube MCP server & CLI

Telegram MCP server & CLI

OP3 MCP server & CLI

The most actionable AI newsletter for founders

Install the CLI. It needs Node 20 or newer.

Give Claude Code the skill, so it knows every command.

Check your setup.

Ask Claude Code to use google-workspace-cli.