csa-google-gmail-calendar

project_tracker_base: CINO Project Tracker:appf7fRQUvY9Iy7sL
project_tracker_table: Projects:tblchmbxSAavvJKaY
project_tracker_record: not yet created
project_source: github:CloudSecurityAlliance-Internal/CINO-Projects/projects/CloudSecurityAlliance/csa-google-gmail-calendar

A Python library and local stdio MCP server over the Gmail and Google Calendar REST APIs, on two pillars:

1. 100% API coverage — all 117 methods, against the 21 the official servers reach.
2. Message analysis — fetch a message as raw MIME and check it: SPF/DKIM/DMARC/ARC verification, header-presentation sanity (Reply-To vs From, brand display names, lookalike domains), spam heuristics, and prompt-injection detection.

The second pillar exists because the first is not enough. A phish impersonating Mailchimp, with a Reply-To on an unrelated free Google account, was delivered to a CSA inbox — and it would have passed SPF, DKIM and DMARC, because those authenticate the sending domain, not the claimed identity. See §9 of the design spec.

Status: implemented. A Backend/PolicyBackend/MCP-tools stack, a local stdio server, an offline test suite, and the config/demo/CI surface described below all exist in src/ and tests/. Only a live probe against a real Google account (task 14 of the first-implementation plan) remains. The Discovery snapshots, operation inventory, and live captures of the official Google MCP servers below are what the design was built against, kept as evidence rather than superseded by the code.

Scope

Out of scope, each needing its own snapshot: Gmail Postmaster Tools, the Admin SDK, Google Workspace Events, and the Apps Script / add-on surfaces.

Coverage

Regenerate with python3 scripts/coverage.py --markdown; per-method detail is analysis/coverage-matrix.csv.

Google MCP is gmailmcp.googleapis.com and calendarmcp.googleapis.com, captured unauthenticated 2026-09-01. Anthropic connector is the claude.ai Gmail and Google Calendar connectors, captured 2026-08-31. They are one Google implementation at two exposure levels, not two products: all 32 shared tools are schema-identical, and the six tools only the connector has are Google-authored too (see analysis/observed-mcp-tools.json).

117 API methods. Google's servers reach 21. The claude.ai connectors reach 26. Neither reaches 91.

Gmail v1

Calendar v3

Grouped by what it does

The shape of the gap, in one line each:

• Google's Gmail server cannot send mail. No send_message, reply or forward. It creates drafts it cannot send, and cannot modify one afterwards.
• Nobody downloads an attachment, though get_message returns attachment_ids and points at a GetMessageAttachment request no surface exposes.
• Nobody touches mailbox settings — 45 methods, 57% of Gmail. Filters, forwarding, delegates, send-as, S/MIME, client-side encryption.
• Nobody permanently deletes anything. Trash is as far as either surface goes.
• Nobody reads calendar ACLs — who can see or edit a calendar, 7 methods.
• Nobody does incremental sync, so every read is a full listing.

Why this exists

Google ships official Gmail and Calendar MCP servers — two of eight Workspace MCP servers — and they are the thing to align with rather than ignore. But they are Google-hosted remote endpoints gated behind the Developer Preview Program. The closest surfaces we have probed, the claude.ai Gmail and Calendar connectors, reach 26 of these 117 methods between them; on the Drive precedent Google's own servers reach the same or fewer.

The gap is not evenly distributed. It is concentrated in exactly the families a security organisation cares about:

• users.settings.* is 45 of Gmail's 79 methods — 57% of the API — and no MCP server exposes any of it. Filters, forwarding addresses, delegates, send-as identities, S/MIME, client-side-encryption keys. A filter that forwards to an external address and archives the original is the canonical mailbox-persistence mechanism after an account compromise. Reading that subtree is a detection capability; writing to it is close to the most dangerous thing an agent can do to a mailbox.
• Calendar acl is 7 methods, 5 of them mutating, exposed by nobody. Who can read and write a calendar.
• The Gmail connector cannot download an attachment. It returns attachment_ids and a description pointing at a GetMessageAttachment request that is not among its tools.

Two further findings shape the design more than the coverage number does:

• Google's published scope lists disagree with Google's own capability claims. The Calendar page lists three read-only scopes on the page that says the server creates and deletes events. The Gmail page omits gmail.modify while describing trash. Scopes must be derived from the Discovery document's per-method scopes array, never from prose.
• Ten Gmail methods cannot be called with user OAuth at all — updateAutoForwarding, delegates.*, forwardingAddresses.create/delete, sendAs.create/delete/verify require a service account with domain-wide delegation. That includes delegates.list, so you cannot enumerate who else can read a mailbox using that mailbox's own token.

Architecture

Fourth in the line after csa-skilljar, csa-google-workspace and csa-zendesk, on the same spine:

Backend (Protocol)   the seam - keyword-only args, returns raw upstream envelopes
    ^ wrapped by
PolicyBackend        capability gating; FAILS CLOSED - an ungated method is refused
    ^ consumed by
Client               thin typed library surface (the public product)
    ^ consumed by
mcp/_tools/*.py      per-family register_*(app, get_client) producers

Enforcement lives in the wrapper around the seam, not in the tools, so a library embedder gets the same guarantee an MCP client does.

What is here

Google publishes Discovery documents, not OpenAPI, and unlike Zendesk it links to them — they are the same artifact its client libraries are generated from, so they are authoritative rather than best-effort. They are still snapshots of a moving target; both were revised within a week of capture. Re-fetch and diff before trusting them.

Prior art was captured live — but from the connectors, not from Google

The tool inventories in analysis/ were taken off the wire from running MCP connections. Those connections are the claude.ai Gmail and Calendar connectors, which are not the same product as Google's gmailmcp/calendarmcp servers: csa-google-workspace verified that for Drive, where the connector ships 11 tools and Google's server 8.

Google's own servers have not been captured. Doing so needs Developer Preview enrollment, gcloud services enable, and an OAuth client. Until then, claims about Google's tool list rest on Google's documentation; only claims about the connectors rest on a probe. PRIOR-ART.md marks which is which.

Alignment: copy, fill, better

Google authored every tool on both official surfaces, so its vocabulary is the vocabulary. The plan has three parts, in order of how much each is owed to them.

Copy — their per-tool conventions, adopted wholesale

• All 29 Gmail and 9 Calendar tool names. Google wrote the six it withholds publicly (send_message, reply, forward, update_draft, update_label, delete_label) as well as the 23 it publishes, so using them costs no invention and no divergence.
• The thread/message axis named in every tool — label_thread vs label_message — which the community server collapses and then cannot express.
• view / messageFormat projections. Framed by Google as economy; METADATA_ONLY returns envelope without body, which makes it a data-minimisation control a caller cannot forget.
• Annotations and outputSchema on every tool, as they do on 32/32. Their annotation logic is right and we adopt it: removing something the user expects to be there is destructive (unlabel_*, trash_*, mark_*_spam); putting it back is not.
• Their six guidance patterns — cross-tool routing, prefer/instead, negative capability, empty-result disambiguation, context-cost steering, upstream-behaviour warnings.

Fill — the gaps inside their own model

• Irreversibility warnings. No tool on any surface says "cannot be undone" or "permanently". Their delete_label reads "Deletes a label in the authenticated user's Gmail account" where the REST API says it "Immediately and permanently deletes the specified label and removes it from any messages and threads that it's applied to." We relay the destructive half — and we ship far more irreversible operations than they do.
• get_attachment. Their get_message returns attachment_ids and points the model at a GetMessageAttachment request no surface exposes.
• The guidance template applied to every tool, not just get_message — the one tool that got "Key indicators" and "Example user prompts" before the rollout apparently stopped.

Better — the layer they have nowhere to put

Their per-tool guidance is good. What has no home in a tool description is anything that is not about one tool, which is why neither server ships it:

• Server instructions — that message content is untrusted data and never instructions; which credentials are configured and what each unlocks; what this deployment is hiding and why.
• MCP resources — the live effective policy and a capability reference, as csa-google-workspace publishes at csa-gw://config. Both official servers return HTTP 404 for resources/list; the method is not routed at all.
• Refusals that can be relayed. A gated-but-registered tool says "capability X is disabled, an operator enables it in configuration". An absent tool reads as "this server cannot do that", and the model goes looking for another route.
• Scope minimisation. Both official servers over-declare: Gmail advertises mail.google.com while shipping no permanent-delete tool; Calendar advertises calendar.acls while shipping no ACL tool. We request the scopes the enabled capabilities need and nothing else.

The one thing we cannot match

search_events is semantic search with no public REST equivalent. events.list offers q, a verbatim AND-match. Shipping keyword search under Google's name for semantic search would be the one lie that is hard to detect from outside, so we do not ship it, and the google flavour says it is absent and why.

Tools

46 tools total under the default (full) flavour with every capability enabled. Generated by python3 scripts/generate_tool_table.py from the live registry (create_server) - never hand-edited; tests/test_docs_drift.py fails if this table falls behind what the server actually registers. core/google columns mark whether a tool survives under that CSA_GGC_FLAVOUR (see "Flavours" below); - in Capability means the tool is exempt from capability gating (the auth-lifecycle and configuration-surface tools).

Capabilities

CSA_GGC_CAPABILITIES gates every mutating and every reading action (policy.py). A capability not enabled means its tools are absent, not present-and-refusing (_capabilities.py).

Unset means the shipped default: every capability except mail.delete and calendar.delete (both irreversible, both off by default). Set an explicit, complete list:

CSA_GGC_CAPABILITIES=mail.read,calendar.read      # exactly these two
CSA_GGC_CAPABILITIES=default,mail.delete          # the usual set, plus permanent delete
CSA_GGC_CAPABILITIES=none                          # nothing enabled (auth + config tools only)

Flavours

CSA_GGC_FLAVOUR=core|google|full restricts which tools are registered, on top of whatever CSA_GGC_CAPABILITIES already allows - never which refuse (_flavours.py).

authenticate/auth_status/logout/describe_configuration/demonstration_plan/ report_a_problem/whoami are exempt from every flavour - narrowing a deployment cannot lock it out of its own login or its own introspection. Call describe_configuration to see exactly what the active flavour hides and why.

Setting up the Google side

This server has no hosted component. It talks to Google as you, using an OAuth client from a Google Cloud project you control — so before it can do anything, that project has to exist. About five minutes, once.

Replace the placeholders with your own values throughout.

1. Create a project

console.cloud.google.com/projectcreate

2. Enable the two APIs

With that project selected:

• Gmail API — library/gmail.googleapis.com
• Google Calendar API — library/calendar-json.googleapis.com

A granted scope is not the same as an enabled API. If you skip this, sign-in succeeds and the first call fails with SERVICE_DISABLED — and because enablement is per-API, Gmail can work while Calendar 403s.

3. Configure the consent screen — and read this part before choosing

APIs & Services → OAuth consent screen (Google now labels this "Google Auth Platform").

User type is the decision that matters, because Gmail's scopes are restricted scopes:

If you have a Google Workspace organization, choose Internal. Google waives both verification and the annual third-party security assessment, which for restricted Gmail scopes is the difference between five minutes and a procurement exercise.

If you do not have a Workspace org, you can still run this: choose External, leave the app in Testing, and add your own account under Test users. Testing mode caps you at 100 test users and re-consent every 7 days, which is fine for one person and not a way to deploy to a team.

The app name is read by whoever consents, at the moment they decide whether to hand over a mailbox. Use something they can resolve — <Your Org> Gmail-Calendar MCP, not an internal codename.

If the app is in Testing with an explicit scope list, add:

.../auth/gmail.modify      .../auth/calendar.events
.../auth/gmail.send        .../auth/calendar.calendarlist.readonly
                           .../auth/calendar.calendars.readonly
                           .../auth/calendar.freebusy

Six, not eight: gmail.modify subsumes gmail.readonly and gmail.compose, and the server collapses subsumed scopes before requesting them, so the consent screen asks for the smallest set that still works. Enabling mail.delete adds https://mail.google.com/; leaving it off — the default — means the full-mailbox scope is never requested.

4. Create the OAuth client

Credentials → Create credentials → OAuth client ID → Application type Desktop app. Download the JSON.

A Desktop client's "secret" is not really secret — Google documents it as such. The security comes from the user consent step and the http://localhost redirect, not from the file being hidden.

5. Put it where the server looks

mkdir -p ~/.csa_google_gmail_calendar && chmod 700 ~/.csa_google_gmail_calendar
mv ~/Downloads/client_secret_*.json ~/.csa_google_gmail_calendar/client_secret.json
chmod 600 ~/.csa_google_gmail_calendar/client_secret.json

Or point CSA_GGC_CLIENT_SECRETS somewhere else.

6. Sign in

csa-google-gmail-calendar login

A browser opens. Check the consent screen against what you expect — it should list the six scopes above and no more. That screen is the clearest view you will get of what this server can reach, and it is worth reading rather than clicking through.

The token lands at ~/.csa_google_gmail_calendar/token.json, mode 0600, written atomically.

If something goes wrong

Configuration

Authenticates as the operating user via OAuth, the same model csa-google-workspace uses. Run csa-google-gmail-calendar login once in a terminal, or call the authenticate tool from inside a session that supports MCP URL elicitation.

Structural absences

Three things a person names that the API does not have (spec §5) - none of these is a gap in this server specifically; they do not exist on Google's Gmail/Calendar REST surface at all:

• There is no move. Gmail has no folders. Every organisational act is addLabelIds/ removeLabelIds on users.messages.modify - move to folder is add a label, archive is remove INBOX, mark read is remove UNREAD, spam is add SPAM. archive_email/ trash_email/mark_spam each name one specific combination rather than exposing the raw label-list edit as the only primitive, per ADR-001.
• There is no attachment upload tool. The only attachment operation Gmail's API has is users.messages.attachments.get (this server's get_attachment, download only - it writes under CSA_GGC_DOWNLOAD_DIR). Sending an attachment is an argument (attachments=[...], a local path under CSA_GGC_ATTACH_DIR) on send_message/create_draft/update_draft/reply/reply_all/forward, not a tool of its own. CSA_GGC_ATTACH_DIR and CSA_GGC_DOWNLOAD_DIR are deliberately two separate variables, never one directory serving both directions - see "Configuration" above.
• There is no receive. Nothing pushes to a client. list_history gives increments and search_messages/list_threads poll; users.watch needs a Cloud project, a Pub/Sub topic and a public HTTPS endpoint, none of which this stdio-only server can offer, so it is omitted rather than shipped broken.

Two further, narrower gaps, tracked in TODO.md rather than fixed here: there is no delete_label/update_label tool yet (Backend's own Protocol has neither method), so a label created by create_label - including the one demonstration_plan creates for its own demo run

• cannot be removed again through this server; and list_history's FakeBackend double needs its history entries seeded explicitly (there is no automatic "every write appends a history record" wiring), which is enough to test the tool but not a full incremental-sync simulation.

Development

python3 -m pytest --cov --cov-fail-under=90    # unit suite, offline, against FakeBackend
ruff check .                                    # lint
mypy                                            # types
python3 scripts/generate_tool_table.py          # regenerate the Tools table above
python3 scripts/coverage.py --markdown          # regenerate the Coverage tables above
python3 scripts/inventory.py                    # regenerate the 117-method inventory

See RELEASING.md for how a release reaches PyPI, and CHANGELOG.md for what shipped when.

License

Apache 2.0.