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.
0.0(0 ratings)- 1
Add it with a single command in a terminal.
claude mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
In Claude Code, type /mcp. Google Workspace should show as connected.
/mcp
- 1
Add it with a single command in a terminal.
claude mcp add google-workspace -- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
In Claude Code, type /mcp. Google Workspace should show as connected.
/mcp
- 1
Add it with a single command in a terminal.
claude mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
In Claude Code, type /mcp. Google Workspace should show as connected.
/mcp
- 1Download the extension
Download the Claude Desktop extension.
- 2
Double-click it, and Claude Desktop installs it.
- 1
Add it with a single command in a terminal.
codex mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Add it with a single command in a terminal.
codex mcp add google-workspace -- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Add it with a single command in a terminal.
codex mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Open Cursor's settings, go to the MCP tab, and click Add new global MCP server.
- 2
Add the server.
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
} - 3
Open the MCP tab again. It should show 38 tools.
- 1
Open the Command Palette and run MCP: Open User Configuration.
- 2
Add the server to that mcp.json.
If the file already has servers, add only this one inside servers.
{
"servers": {
"google-workspace": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
}
- 1
Add it with a single command in a terminal.
copilot mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get google-workspace
- 1
Add it with a single command in a terminal.
copilot mcp add google-workspace -- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get google-workspace
- 1
Add it with a single command in a terminal.
copilot mcp add google-workspace \
-- npx -y @thenavidm/google-workspace-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get google-workspace
- 1
Open your Gemini CLI settings.
~/.gemini/settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your Gemini CLI settings.
%USERPROFILE%\.gemini\settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your Gemini CLI settings.
~/.gemini/settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your OpenCode config.
~/.config/opencode/opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"google-workspace": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/google-workspace-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Open your OpenCode config.
%USERPROFILE%\.config\opencode\opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"google-workspace": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/google-workspace-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Open your OpenCode config.
~/.config/opencode/opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"google-workspace": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/google-workspace-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Add it with a single command in a terminal.
openclaw mcp add google-workspace \
--command npx \
--arg -y \
--arg @thenavidm/google-workspace-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor google-workspace --probe
- 1
Add it with a single command in a terminal.
openclaw mcp add google-workspace --command npx --arg -y --arg @thenavidm/google-workspace-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor google-workspace --probe
- 1
Add it with a single command in a terminal.
openclaw mcp add google-workspace \
--command npx \
--arg -y \
--arg @thenavidm/google-workspace-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor google-workspace --probe
- 1
In the agent panel, click the … menu, then MCP Servers, Manage MCP Servers and View raw config.
- 2
Add the server to mcp_config.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
}
}
}
- 1
Open your Hermes config.
~/.hermes/config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
google-workspace:
command: "npx"
args: ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
- 1
Open your Hermes config.
%USERPROFILE%\.hermes\config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
google-workspace:
command: "npx"
args: ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
- 1
Open your Hermes config.
~/.hermes/config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
google-workspace:
command: "npx"
args: ["-y", "@thenavidm/google-workspace-mcp-cli@latest"]
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 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.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 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.
New-Item -ItemType Directory -Force "$HOME\.claude\skills\google-workspace" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\google-workspace-mcp-cli\SKILL.md" "$HOME\.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.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 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.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.agents/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Codex to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.agents\skills\google-workspace" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\google-workspace-mcp-cli\SKILL.md" "$HOME\.agents\skills\google-workspace\" - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Codex to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.agents/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Codex to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
Ask Cursor to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Cursor finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
Ask VS Code to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so VS Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.copilot/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Copilot CLI to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.copilot\skills\google-workspace" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\google-workspace-mcp-cli\SKILL.md" "$HOME\.copilot\skills\google-workspace\" - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Copilot CLI to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.copilot/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask Copilot CLI to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
Ask Gemini CLI to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Gemini CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.config/opencode/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenCode to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\google-workspace" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\google-workspace-mcp-cli\SKILL.md" "$HOME\.config\opencode\skills\google-workspace\" - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenCode to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.config/opencode/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenCode to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.openclaw/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenClaw to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.openclaw\skills\google-workspace" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\google-workspace-mcp-cli\SKILL.md" "$HOME\.openclaw\skills\google-workspace\" - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenClaw to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/google-workspace
cp "$(npm root -g)/@thenavidm/google-workspace-mcp-cli/SKILL.md" ~/.openclaw/skills/google-workspace/ - 3
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 4
Ask OpenClaw to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
Ask Antigravity to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Antigravity finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
Ask Hermes to use google-workspace-cli.
Running google-workspace-cli on its own lists every command, so Hermes finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/google-workspace-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
google-workspace-cli doctor - 3
List every command, then try one.
google-workspace-cli
google-workspace-cli calendar-list-events
Needs Node 22 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.
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 two 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.
In this guide, I'll show you:
- What the Google Workspace MCP server & CLI is, and what you can ask it
- How to install it and check that it works
- When to use the MCP server, and when the CLI
- Every tool, and how to keep your account safe
Every tool on this page comes from the server itself, and every cost was measured in Claude Code.
Key takeaways
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 two 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.
In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Google Workspace. My guide to building an AI operating system names Google Workspace among the tools it reaches, and here's how I use AI myself.
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 askingWhat 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.
It works well next to my Calendly MCP server and iMessage MCP server, so your AI can book meetings at open times and text people from your Mac in the same chat. Every server I've made is on my MCP servers page.
For your email and calendar, my free Gmail signature generator and time zone converter help too.
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.
Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:
| App | Where the block goes |
|---|---|
| Windsurf | In the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block. |
| Cline | Click the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block. |
| Zed | Go to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers. |
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.
brew install googleworkspace/tap/gws. Other systems download a binary from its releases.gws auth login.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.
In Claude Code, /mcp also shows whether the Google Workspace server is connected. It's one of the Claude Code commands worth knowing.
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, google-workspace-cli which <words> finds the command for a task, 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 need --confirm, the terminal's version of your approval.
google-workspace-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.
These are the flags you'll use most:
| Flag | What it does |
|---|---|
--json | Prints JSON |
--compact | Prints the JSON on one line |
--select a,b.c | Keeps only those fields, and a dotted path goes deeper |
--agent | Machine mode: compact JSON, no prompts, and it never confirms anything |
--confirm | Lets a write that asks first go ahead |
--dry-run | Shows what a write would do, without doing it |
A script can branch on the exit code:
| Exit code | What it means |
|---|---|
| 0 | It worked |
| 1 | Something unexpected went wrong |
| 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 failed or couldn't be reached |
| 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.
- MCP server
- 5,700 tokens
- CLI
- Nothing
- MCP server
- 810 tokens
- CLI
- Nothing
- MCP server
- Nothing more, or in Claude Code the tools it picks
- CLI
- 1,800 tokens, once
- MCP server
- 114,000 tokens
- CLI
- 1,800 tokens
- MCP server
- Yes
- CLI
- No, there's no terminal there
- MCP server
- No
- CLI
- 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 130 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 October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.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 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
The tables below list all 38 tools, grouped the way the repo groups them. Of these, 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
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
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
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
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
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
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
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
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
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
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 first, marked "Asks first" in the tool tables above.
When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:
- Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
- An app that can show forms asks you in a form.
- Any other app takes your AI's
confirm: trueas the yes, so tell your AI to check with you first. - An agent with no person to ask needs
GWS_CONFIRM=model, so itsconfirm: truecounts in every app. - In a terminal, you add
--confirmto the command.
If the answer is no, nothing reaches Google Workspace.
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
gwson 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
1refuses 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
--httprequires
GWS_ALLOW_DESTRUCTIVE- Default
- on
- What it does
0refuses the writes that can't be undone
GWS_TOOLSETS- Default
all- What it does
- Turns on only the toolsets you name, comma separated
GWS_SURFACE- Default
full- What it does
searchlists three tools that find, describe and run the rest
GWS_AUDIT_LOG- Default
- none
- What it does
- Names a file that gets one line per attempted write
GWS_TOOL_TIMEOUT_MS- Default
- none
- What it does
- Gives up on any tool after this many milliseconds
GWS_CONFIRM- Default
human- What it does
modellets your AI'sconfirm: trueapprove on its own, for an agent with no person to ask
GWS_HTTP_PORT- Default
8787- What it does
- Sets the port for
--http
GWS_HTTP_HOST- Default
127.0.0.1- What it does
- Sets the address for
--http, and any other needs a token
GWS_HTTP_TOKEN- Default
- none
- What it does
- Sets the bearer token every
--httprequest needs
GWS_HTTP_ALLOWED_ORIGINS- Default
- none
- What it does
- Lists other websites allowed to call
--http, comma separated
GWS_DEBUG- Default
- off
- What it does
1prints debug lines
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.
Free tools
FAQs about the Google Workspace MCP server & CLI
Here are the questions people ask most about the Google Workspace MCP server and 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.
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.
Every server I've made is on my MCP servers page.
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.
One npm package installs both.
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.
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.
No, the Google Workspace MCP server drafts email and stops.
Sending is a separate tool that asks first, because a sent email can't be recalled.
No, your credential belongs to Google's Workspace CLI, and the server never sees or stores it.
Signing in happens in your own browser.
Yes, run a second copy with GOOGLE_WORKSPACE_CLI_CONFIG_DIR pointing at another folder.
Add it to your app under a different name.
No, drive_trash moves a file to the trash, where it stays recoverable for 30 days, and there is no hard delete.
Trashing asks first.
The Google Workspace MCP server works with any app that speaks MCP.
That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.
I did.
I'm Navid Moazzez, and I made the Google Workspace MCP server & CLI as one of my free tools on navid.me.
You can read more about me.
The code is on GitHub under the MIT license, and the package is on npm.
More MCP servers & CLIs
Related free tools
Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.
On this page
The most actionable AI newsletter for founders
Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.
No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.
P.S. Sign up now to get free access to my ultimate AI tools guide for creators.
