Provides Gmail integration, enabling agents to read, send, and modify emails, including managing messages and drafts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Google Workspace MCP show me my calendar events for tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
v2.1 changed all list tools from bare arrays to cursor envelopes
(items, next_page_token, has_more). See
docs/MIGRATION-v2.md. Pin the v2.0 tag to stay
on the old shapes.
Wrappers that trim API responses make agents decide on incomplete data. This server goes the other way:
Reads return the decision-useful resource, with a full=True hatch to the
complete payload where one exists
Cursor envelopes (items, next_page_token, has_more) on all 11 list
tools, so collections of any size are walkable
Every mutation is staged first: preview plus checks plus operation_id,
then a single-use commit that revalidates, or a cancel
One env var (GOOGLE_WORKSPACE_HOME) points at all state, so any stdio
MCP host can run it
No tools were removed in v2.1. Ten list shapes changed; see the migration guide.
Related MCP server: google-connections-mcp
Eleven Google Workspace services behind one server:
Gmail search, reads, thread summaries, labels, attachment downloads, staged sends
Drive search, metadata, inline text reads, recency, downloads, uploads, creates, folders, sharing audit, copy, move, trash
Docs reads (all tabs), creates, appends, staged batch updates
Sheets metadata, reads, updates, appends, creates, dimension inserts, conditional-format reads
Slides reads, creates, staged batch updates
Forms definitions, responses, listings
Calendar lists, events, calendars, search, RSVP, time suggestions, patches, deletes, free/busy
Contacts lists, server-side search, single reads, own profile
Tasks lists, reads, creates, patches, deletes
Chat spaces, search, messages, members, read-state, staged sends
Meet spaces, reads, staged creates
Universal cross-product search, 4 guided prompts (inbox triage, meeting brief, thread summary, find-anything)
flowchart LR
Client[MCP client] --> Stdio[MCP stdio]
Stdio --> Tools[73 Workspace tools + 4 prompts]
Tools --> Stage[Staged-write gate]
Stage --> Google[Google APIs]
Tools --> State[(State home)]
State --> Token[OAuth token + client]
State --> Audit[Audit log]Python 3.11+ (developed and CI-tested on 3.14; .python-version pins 3.14)
A Google Cloud project with the 11 Workspace APIs enabled and a Desktop
OAuth client (see docs/SKILL.md for the click path)
An MCP client that can launch stdio
git clone https://github.com/cikeyz/google-workspace-mcp.git
Set-Location google-workspace-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:GOOGLE_WORKSPACE_HOME = "$PWD\state"
python setup/setup.py --client-secret C:\path\to\client_secret.json
python setup/setup.py --auth-urlOpen the printed URL, approve all scopes, then exchange the redirect:
python setup/setup.py --auth-code '<paste-the-redirect-url>'
python setup/tests/verify_server.pyExpect RESULT: ALL CHECKS PASSED.
git clone https://github.com/cikeyz/google-workspace-mcp.git
cd google-workspace-mcp
python3.14 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GOOGLE_WORKSPACE_HOME="$PWD/state"
python setup/setup.py --client-secret /path/to/client_secret.json
python setup/setup.py --auth-url
python setup/setup.py --auth-code '<paste-the-redirect-url>'
python setup/tests/verify_server.pyTesting-mode OAuth clients need weekly re-consent unless the app is verified.
{
"mcpServers": {
"Google Workspace": {
"command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
"args": ["C:\\path\\to\\server.py"],
"env": {
"GOOGLE_WORKSPACE_HOME": "C:\\path\\to\\state"
}
}
}
}Tool family | Purpose | Key inputs |
| Search, read, thread summaries |
|
| Labels |
|
| Save attachments locally |
|
| Send mail |
|
| Find and describe files |
|
| Inline text reads (Docs/Slides text, Sheets CSV) |
|
| Fetch and store files |
|
| Organize |
|
| Share and audit sharing |
|
| Recoverable delete |
|
| Read and write docs |
|
| Structural doc edits (insert, delete, replace, style) |
|
| Inspect and read sheets |
|
| Write cells |
|
| Insert rows/columns |
|
| Read format rules |
|
| Read and create decks |
|
| Structural deck edits (slides, text, replace) |
|
| Forms and answers |
|
| Events |
|
| Discover calendars |
|
| Free-slot suggestions |
|
| Manage events + RSVP |
|
| Availability windows |
|
| Contacts + profile |
|
| Read tasks |
|
| Manage tasks |
|
| Rooms and history |
|
| Read-state |
|
| Post messages |
|
| Cross-product fan-out |
|
| Guided workflows | per-prompt args |
| Meetings |
|
| Auth health | none |
| Apply staged writes |
|
Writes never apply directly. Stage, review, then commit:
{ "tool": "google_docs_create", "title": "GW-TEST-doc" }returns { "staged": true, "operation_id": "…", "preview": {…} }, then:
{ "tool": "google_write_commit", "operation_id": "…" }Commits revalidate first and refuse on drift. Cancels and failures are logged
alongside commits in logs/google-write-audit.jsonl.
page = gmail_search("is:unread", 10)
msgs = page["items"]
while page["has_more"]:
page = gmail_search("is:unread", 10, page_token=page["next_page_token"])
msgs += page["items"]Empty results are {"items": [], "has_more": false}, never an error.
Variable | Default | Purpose |
|
| State home: token, client secret, downloads, audit log |
|
| OAuth token override |
|
| OAuth client override |
|
| Download target |
|
| OAuth redirect override |
| Empty | Test fixture: readable Doc |
| Empty | Test fixture: readable Form |
|
| Test fixture: sheet range |
Stdio only. No listening ports, no network surface beyond Google's own APIs.
state/ holds a Gmail-capable OAuth grant. Keep the directory
user-private and never commit it (already in .gitignore).
Staged writes expire after 24h, cap at 20 concurrent, and fail closed in cron sessions.
The audit log records write metadata with bodies redacted to counts and hashes. Treat it as sensitive.
Testing-mode OAuth clients need weekly re-consent unless verified.
$env:GOOGLE_WORKSPACE_HOME = "$PWD\state"
.\.venv\Scripts\python.exe setup\tests\verify_server.py
.\.venv\Scripts\python.exe setup\tests\test_server.pyverify_server.py is the quick battery (no writes). test_server.py runs
full stage-commit-verify-cleanup cycles across services and must finish with
RESULT: ALL CHECKS PASSED and zero GW-TEST- residue. Set
GW_FIXTURE_DOC_ID and GW_FIXTURE_FORM_ID for full coverage; fixture checks
skip otherwise.
Repository:
cikeyz/google-workspace-mcp
Original project: written from scratch for personal agent use, no upstream.
Released under the MIT License.
Fork the project
Create your feature branch (git checkout -b feature/my-change)
Commit your changes (git commit -m 'Add my change')
Push to the branch (git push origin feature/my-change)
Open a Pull Request
Reads are free to add. Anything mutating must fit the staged-write protocol (stage, preview, single-use commit) and land in both test batteries.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Your workspace as agent tools — docs, canvases, slides, sheets, projects, tickets, and a shell.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
