Mariana Google MCP
Summary: This server gives Claude multi-account access to Gmail, Google Calendar, and Contacts for reading, drafting, and reversible/soft cleanup work.
Authenticate Google accounts and check connection/token health.
Gmail: search, read full messages, list labels, create unsent drafts, and soft-delete by moving messages to a 'To Be Deleted' label.
Calendar: list, search, and get events; create/update events; flag events with 'DELETE - '; check free/busy availability.
Contacts: search by name/email/phone and list contacts, optionally by group.
Multi-account support through
account_name/account, defaulting to the primary account.Safety intent from README: no send tool, no permanent delete, and writes are logged.
Schema caveat: it exposes
send_invites/send_updateson calendar create/update despite README saying invites/updates are hardcoded off, and it exposes 18 tools vs README's stated 26.
Provides email management capabilities including searching messages, reading full content, listing labels, creating drafts, and soft-deleting via labels, with safety-first defaults that prevent sending emails or permanent deletion.
Enables calendar event management including listing, searching, creating, and updating events with availability checking, featuring safety constraints that prevent automatic invite notifications and use title prefixing for soft-deletion instead of permanent removal.
Click on "Deploy 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., "@Mariana Google MCP draft an email to john about tomorrow's meeting"
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.
mariana-google-mcp
A custom MCP (Model Context Protocol) server that gives Claude Code access to Gmail, Google Calendar, and Google Contacts, with safety-first defaults. The agent can read and draft, but nothing leaves your account without you. There is no send tool and no forwarding, and the server never sends calendar invites or updates. Nothing is permanently deleted: cleanup moves mail to Trash (recoverable for 30 days), and filters that hide mail must name a single sender and can never touch protected senders (security, sign-in and money mail). Every write is logged, including failed and refused attempts.
Who this is for: operators who want Claude to help run their Google inbox and calendar, while sending and deleting stay in their own hands.
These are the guarantees the code enforces. Where one depends on your own configuration (for example, how broad you make attachmentRoots), the section below says so. See What this does not protect against for the limits.
The 22 tools this server gives Claude Code, with abridged descriptions. Dotted tools write to your account and are logged.
Quick start
git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install && npm run buildThen add the server to Claude Code and run google_auth (steps 3 and 4 under Setup). You need your own Google Cloud OAuth credentials first (step 1).
Related MCP server: gmail-drive-mcp-server
Design Philosophy
This server is built for an operator who wants AI to help manage their Google workspace without risk of accidental damage:
No sending email. You can draft, but sending requires manual action in Gmail. There is no send tool and no forward option anywhere, including filters.
Filters are bounded.
gmail_create_filtertakes a fixed action list. Visibility actions (star, one of your ownLabel_*labels, important) accept any criteria. Cleanup actions (trash, archive, mark read) and never-spam require ONE sender (an address or a domain), optionally narrowed by subject, with notoorquery, so a filter cannot sweep broad mail out of sight. Shared domains (gmail.com, outlook.com, co.uk-style suffixes) need a full address, and those subjects must be plain words. All four refuse protected senders, matched the way Gmail tokenizes (soaccounts.googleorservice.paypalcount too) (Google, Apple, Microsoft, GitHub, PayPal, 1Password, Anthropic, plus your ownprotectedSenders). The exact request sent to Google is unit-tested.No deleting your mail. Gmail uses a "To Be Deleted" label (soft-delete). Calendar prepends "DELETE - " to event titles. You review and confirm in the Google UI. The single exception is your own unsent drafts (
gmail_delete_draft), which move to Trash (recoverable for 30 days). There is no permanent-delete option.Trash only through
gmail_trash. It moves up to 500 messages per call to Trash (recoverable for 30 days; there is no permanent delete), and refuses the whole batch if any message is from a protected sender.gmail_apply_labelrefuses theTRASHandSPAMlabels.gmail_remove_labelwithINBOXarchives a message; that is recoverable (the message stays in All Mail).No invites. Calendar writes always use
sendUpdates: "none"(hardcoded, not a parameter), so Google never emails guests about events this server creates or changes.Every write is logged. An append-only JSONL action log records every write with timestamps, tool name, account, and summary. Failed and refused attempts are logged too.
Multi-account support. Manage personal and work accounts with named aliases.
Setup
Easiest path: paste this one line into Claude Code and it will run the entire setup for you, including guiding you through the Google Cloud clicks:
Fetch https://raw.githubusercontent.com/marianasmall/mariana-google-mcp/main/SETUP-PROMPT.md and follow the instructions in it.
See SETUP-PROMPT.md for what it does, including an optional phase that unifies triage across multiple accounts. The manual steps below cover the same ground.
1. Google Cloud Project
Go to Google Cloud Console
Create a new project (or use an existing one)
Enable these APIs:
Gmail API
Google Calendar API
People API (for Contacts)
Create OAuth 2.0 credentials:
Application type: Desktop app
Download the client ID and client secret
2. Install and Build
git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build3. Add to Claude Code
Add this to your ~/.claude.json under mcpServers:
{
"mcpServers": {
"mariana-google-mcp": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mariana-google-mcp/dist/index.js"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}Replace /path/to/ with the actual path to your clone, and fill in your OAuth credentials.
4. Authenticate
After restarting Claude Code, run the google_auth tool. It will open a browser window for OAuth consent. Once authorized, your token is stored locally and refreshed automatically.
How the sign-in is protected:
The consent callback listens on
127.0.0.1only (a random local port), never on a network address.The flow uses a random
statevalue and PKCE, so a forged or intercepted callback is rejected.An existing account name cannot be silently re-bound to a different Google account. Using a name that already belongs to another address is refused; pick a new name or remove the old one from
config.jsonyourself.This needs a Google OAuth client of type Desktop app. A "Web application" client cannot register the random-port loopback redirect, and sign-in will fail.
Scopes
The server requests exactly these seven scopes (defined in src/auth.ts):
Scope | Why |
| Learn which Google account signed in |
| Read mail, create and edit drafts, apply labels. Google's scope is broader than the tools use (on Google's side it also covers sending and trashing), so the limits come from the tools this server exposes, not from the scope |
| List, create and delete filters. Google's scope also covers other basic settings; the tools only touch filters, with the limits above (no forwarding) |
| Create and edit events on calendars you own |
| Check that you own a calendar before writing to it |
| The availability tool |
| Check that event guests are in your saved contacts |
Re-consent after upgrading
Earlier versions asked for full Calendar access (calendar). The 2026-11-13 hardening dropped gmail.settings.basic along with the old unrestricted filter tool; 2026-11-16 brought the scope back for the safe-actions-only filter tools. A token only carries the scopes it was granted at sign-in, so re-run google_auth for each account after upgrading so the stored token carries exactly the seven scopes above, then restart Claude Code so the rebuilt server loads. You can also remove the old grant at https://myaccount.google.com/permissions before signing in again.
Available Tools (26)
Authentication & Status
Tool | Description |
| Authenticate a Google account via OAuth browser flow |
| Check connection health for all configured accounts |
Gmail (15 tools)
Tool | Description |
| Search messages using Gmail query syntax |
| Read a specific message by ID (full content) |
| List all Gmail labels/folders |
| Create a draft email: plain text or rich HTML body, optional file attachments, optional reply-in-thread via |
| Create a new label (supports nesting with |
| Apply a label to one or more messages (refuses |
| Remove a label from one or more messages (removing |
| List the account's filters (read-only) |
| Create a filter for new mail: star, own label, important (any criteria); trash, archive, mark read, never spam (one sender only; protected senders refused). No forwarding |
| Delete a filter by ID; logs the rule it removed. Touches no mail |
| Move up to 500 messages to Trash (recoverable 30 days; no permanent delete) |
| Soft-delete: move messages to a "To Be Deleted" label |
| List current drafts with IDs, subjects, recipients, thread |
| Revise a draft in place, preserving its thread and threading headers |
| Move a draft to Trash (30-day recovery). No permanent option |
Calendar (7 tools)
Tool | Description |
| List upcoming calendar events |
| Search events by keyword |
| Get full details of a specific event |
| Create an event (never sends invites; guests must be allowed, see Calendar guests) |
| Modify an existing event (never notifies guests; same guest rules) |
| Soft-delete: prepend "DELETE - " to event title |
| Check free/busy status for a date range |
Contacts (2 tools)
Tool | Description |
| Search contacts by name, email, or phone |
| List contacts, optionally filtered by group |
Multi-Account Support
You can authenticate multiple Google accounts with friendly names:
google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"Most tools accept an optional account parameter. If omitted, they use the default account. Use google_status to see all configured accounts and their health.
Configuration Files
All configuration is stored in ~/.config/mariana-google-mcp/:
File | Purpose |
| Account registry (names, email hashes, defaults) plus the optional |
| OAuth tokens per account (auto-refreshed) |
| Append-only log of all mutations |
Permissions: the config directory and tokens/ are 0700; config.json, the token files and the action log are 0600 (owner-only). The server re-applies these on every start and never follows a symlink when it does.
Tokens are stored under a hash of the email address, not the plaintext address, for a layer of indirection. The hash is an unsalted SHA-256. It only names the token file, so it is not a secret and is not meant to hide the address from someone who already has the config directory; salting it would orphan existing token files and force a re-consent, which is not worth it for a file name.
Settings you can add to config.json
All four are optional. Edit config.json yourself. No tool changes these settings, and the attachment guard refuses to read the config directory.
{
"attachmentRoots": ["/absolute/path/to/outbox", "/absolute/path/to/proposals"],
"allowedAttendees": ["partner@example.com", "assistant@example.com"],
"allowedImageHosts": ["images.example.com"],
"protectedSenders": ["mybank.example", "alerts.mycard.example"]
}Add these next to the existing accounts entries, not instead of them. Folder paths must be absolute: the server does not expand ~, and a root that does not resolve is simply ignored, so nothing from it can be attached.
attachmentRoots is the list of folders gmail_draft may attach files from. If you leave it out, the defaults are ~/Projects, ~/Documents, ~/Downloads, ~/Desktop and ~/Library/CloudStorage. Listing your own folders replaces the defaults, so a narrow list (one dedicated outbox folder) is the safest choice. A guarantee depends on this: if you add a broad folder (your whole home directory, say), anything inside it that is not otherwise blocked can be attached to a draft. Regardless of the roots, these are always refused:
anything inside the config directory or
tokens/, or inside~/.claudeor~/.sshanything inside a hidden folder, or a hidden file
files that look like keys or credentials (
id_rsa-style names,.pem,.key,.p12,.pfx,.keychain-db,.env*,credentials.json,token.json)
The path is resolved to its real location first, so symlinks and .. cannot be used to step outside a root. Every rejection returns the same message, so the error does not reveal whether a given file exists. Total attachment size is capped at 20MB.
allowedAttendees is a list of addresses that may be added as calendar guests even though they are not in your Google Contacts. See Calendar guests. Default: empty.
allowedImageHosts is a list of hostnames whose images may appear in an HTML draft (<img src> only; CSS can never load anything). By default an HTML draft with a remote image is refused (see Remote resources in HTML drafts). An entry lets an image through only if its URL is https:, its hostname equals the entry exactly (case does not matter), and it has no username, password, explicit port or trailing dot. There are no subdomain wildcards, so example.com does not allow images.example.com, and http: is never allowed. Use it for something like an email-signature logo hosted on your own domain. Only list hosts you control: whoever runs a listed host sees a request every time a draft is opened. Default: empty.
protectedSenders adds domains (subdomains included) whose mail a filter may never trash, archive or mark read, on top of the built-in list (Google, Apple, iCloud, Microsoft, GitHub, PayPal, 1Password, Anthropic). Put your banks, card issuers and anything that sends sign-in codes here; it stays on your machine rather than in a public repo. Default: empty.
Other input checks
Carriage returns and line feeds are refused in
to,ccandbcc(header injection), on bothgmail_draftandgmail_update_draft. Line breaks in theIn-Reply-ToandReferencesvalues are refused too.HTML drafts are checked against an allowlist by
gmail_draftandgmail_update_draft, because Gmail loads remote resources when the draft is opened. Anything outside the allowlist is refused (not stripped), and the draft saved is a clean re-written copy of the checked HTML. See "What this does not protect against" below.
Calendar guests
The server never sends invites or updates (sendUpdates is hardcoded to "none"). Even so, a guest added to an event can see it on their own calendar if Google shows it to them, so guests are restricted:
A guest must be in your saved Google Contacts ("My Contacts"), or be listed in
allowedAttendees, or be your own address. "Other contacts" (people Gmail added because they emailed you) are deliberately not trusted, because a stranger could get themselves added by sending you mail. If an address is not allowed, the event is refused.Writes go only to calendars your account owns. Calendars shared with you by other people are refused.
A calendar you own but have shared with others, or made public, will expose anything the agent writes there. Checking sharing would need the full calendar scope, which this build deliberately dropped.
If an event already has a guest who is not allowed,
calendar_updaterefuses to change the title, description or location (the guests would read the new text). Changing the time is still allowed.If the contacts lookup itself fails, the check fails closed: only
allowedAttendeesguests pass.
A side effect to know about: whether a create or update succeeds or is refused tells the agent whether an address is in your contacts. That is a small amount of information about your address book, and the agent can reach it by trying addresses.
Action Log
Every write operation (drafts, label changes, calendar creates/updates, soft-deletes) is logged to ~/.config/mariana-google-mcp/action-log.jsonl in this format:
{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}Failed and refused write attempts are logged as well, with an outcome of "failed" or "refused". The message is short (about 300 characters), newlines are collapsed, and credential-shaped strings (bearer tokens, Google access and refresh tokens) are redacted. The log does not store request bodies or message text; a draft entry records the subject and the To, Cc and Bcc recipients.
The server only ever appends to the log. Review it anytime to audit what Claude has done. (Anything with write access to your account directory could edit it, so treat it as an audit aid, not tamper-proof evidence.)
What this does not protect against
Opening a draft is enough to leak through remote images. Gmail loads remote images and stylesheets as soon as you open a draft, with no click, so an injected instruction could hide your data in an image URL. That is why
gmail_draftandgmail_update_draftread an HTML body with a standards-compliant HTML parser (parse5, the same parsing rules browsers follow) and accept only basic email formatting:Elements:
html,head,body,meta(withcharsetonly),p,br,div,span,b,strong,i,em,u,s,small,sub,sup,blockquote,pre,code,h1toh6,ul,ol,li,hr,a,img, the table elements (table,thead,tbody,tfoot,tr,td,th,caption,colgroup,col),centerandfont. Anything else (<style>,<script>,<iframe>,<link>,<base>,<svg>, forms and so on) is refused.Attributes: layout and text attributes (
dir,align,valign,width,height,colspan,rowspan,cellpadding,cellspacing,border,bgcolor,color,face,size,title,alt,lang,style). Links:<a href>with an absolutehttp,https,mailtoorteladdress, plustargetandrel. Images:<img src>set to acid:attachment, a base64data:image(png, jpeg, gif or webp), or anhttpsURL on a host inallowedImageHosts. Everything else (class,id,onclickand other event handlers,srcset,background, ...) is refused.Inline CSS:
style="..."may set color, background color, font, text alignment and decoration, line height, letter spacing, padding, margin, borders, width and height, vertical alignment, display, white-space and list style. Values are plain words, numbers, colors andrgb()/rgba(). Anything that could load a file (url(...),image-set,@import), CSS escapes, comments and line breaks are refused.
HTML comments and doctypes are dropped, and the draft that gets saved is re-written from the checked document, so what Gmail receives is exactly what was checked. A URL typed as plain text in the body is fine, because text never loads anything. Plain-text drafts are unaffected.
A draft Claude prepared or edited. Before sending any draft Claude created or changed, check To, Cc, Bcc and the attachments. An injected instruction could address a draft to a stranger or attach a file from an allowed folder, and
gmail_update_draftcan change a draft you wrote yourself.Mail the agent reads. Anything in your inbox or calendar can contain instructions aimed at the agent (prompt injection). The tools above limit what a hijacked agent can do, but they do not stop it from reading, labeling, archiving or drafting.
Anything else holding your token. The
gmail.modifyscope can send mail at Google's level. This server never does, but another program with access to the token file could. That is why the tokens are0600and the config directory0700.A broad
attachmentRoots. See above: you decide what is attachable.A compromised machine or config. Anyone who can edit
config.jsoncan widenattachmentRootsandallowedAttendees.
Fork and Use
To use this with your own Google account:
Fork this repo
Create your own Google Cloud project and OAuth credentials (see Setup above)
Build and point your Claude Code config at your fork's
dist/index.jsRun
google_authto authenticate
No code changes needed. All account-specific data lives in config files and environment variables.
Tech Stack
TypeScript
@modelcontextprotocol/sdk: MCP protocol implementationgoogleapis: Google API clientgoogle-auth-library: OAuth2 token managementzod: Input validation
License
MIT
Available Tools
16 toolscalendar_availabilityC
Check free/busy status for a date or date range.
Inputs: date_start (required), date_end, calendar_id, account.
calendar_createA
Create a calendar event. Does NOT send invites by default.
Inputs: title (required), start (required), end (required), description, +5 more.
calendar_flag_deleteA
Soft-delete: prepend 'DELETE - ' to event title. Does NOT actually delete the event.
Inputs: event_id (required), calendar_id, account.
calendar_getA
Get full details of a specific calendar event.
Inputs: event_id (required), calendar_id, account.
calendar_listB
List upcoming calendar events.
Inputs: days_ahead, calendar_id, account.
calendar_searchC
Search calendar events by keyword.
Inputs: query (required), time_min, time_max, calendar_id, +1 more.
calendar_updateA
Modify an existing calendar event. Does NOT notify attendees by default.
Inputs: event_id (required), title, start, end, +5 more.
contacts_listC
List Google Contacts, optionally filtered by contact group.
Inputs: group, account, max_results.
contacts_searchB
Search Google Contacts by name, email, or phone number.
Inputs: query (required), account, max_results.
gmail_draftA
Create a draft email. Does NOT send — the draft appears in Gmail for manual review and sending.
Inputs: to (required), subject (required), body (required), cc, +2 more.
gmail_list_labelsB
List all Gmail labels/folders for an account.
Inputs: account.
gmail_move_to_deleteA
Soft-delete: move messages to a 'To Be Deleted' label. Does NOT delete or trash messages.
Inputs: message_ids (required), account.
gmail_readA
Read a specific Gmail message by ID. Returns full message content.
Inputs: message_id (required), account.
gmail_searchA
Search Gmail messages. Uses Gmail search syntax (e.g. 'from:name subject:topic').
Inputs: query (required), account, max_results.
google_authA
Authenticate a Google account. Opens a browser for OAuth consent. Use this to add a new account or re-authenticate an existing one.
Inputs: account_name.
google_statusA
Check connection health for all configured Google accounts. Shows token status and last action.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Tools are cleanly separated by domain (calendar_, contacts_, gmail_, google_) with distinct actions within each domain. No overlapping functionality between tools like calendar_flag_delete and gmail_move_to_delete, as prefixes clearly indicate target services.
Consistent snake_case throughout with clear resource_action pattern (e.g., calendar_create, gmail_read, contacts_search). All 16 tools follow the same naming convention without mixing styles or verb forms.
16 tools is slightly above the ideal 3-15 range but reasonable given it covers three distinct Google services (Calendar, Gmail, Contacts) plus authentication. Each tool serves a specific purpose without redundancy.
Calendar has strong CRUD coverage (create, get, update, list, search, soft-delete). Gmail covers reading, drafting, and soft-delete but lacks send functionality (by design). Contacts is notably incomplete with only read operations (list/search) and no create, update, or delete capabilities.
Maintenance
Related MCP Connectors
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables Claude to interact with Google Workspace services including Gmail, Drive, Sheets, Docs, and Calendar. Provides comprehensive tools for reading, creating, and managing emails, files, spreadsheets, documents, and calendar events with built-in safety controls and audit logging.-
- AlicenseNot gradedqualityDmaintenanceEnables Claude to manage Gmail, Google Calendar, and Google Drive, including sending emails, scheduling meetings, and organizing files, with integrated workflows.5MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to manage Google Workspace services such as Calendar, Gmail, and Docs with configurable access and safe-by-design limitations.2-
- AlicenseNot gradedqualityBmaintenanceEnables Claude to access and manage multiple Google accounts at once across Gmail, Calendar, Drive, Contacts, and Tasks, with unified search and document text extraction.MIT