Mariana Google

A custom MCP (Model Context Protocol) server that gives Claude Code access to Gmail, Google Calendar, and Google Contacts, with safety-first defaults. Email itself is never sent: there is no send tool. Mail and events are moved or flagged, never deleted. Every write is logged. Three opt-in exceptions: a filter can forward, a calendar event can invite, and your own unsent drafts can be trashed (or permanently removed on an explicit flag).

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 by default.

License Built with Claude Code Last commit

The 23 tools this server gives Claude Code, with descriptions taken from the source. 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 build

Then 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).

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.
• 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), and that defaults to Trash (recoverable for 30 days), with permanent removal behind an explicit flag.
• Every mutation is logged. An append-only JSONL action log records every write operation with timestamps, tool name, account, and summary.
• 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

1. Go to Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable these APIs:
   • Gmail API
   • Google Calendar API
   • People API (for Contacts)
4. 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 build

3. 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.

Available Tools (23)

Authentication & Status

Tool	Description
google_auth	Authenticate a Google account via OAuth browser flow
google_status	Check connection health for all configured accounts

Gmail (12 tools)

Tool	Description
gmail_search	Search messages using Gmail query syntax
gmail_read	Read a specific message by ID (full content)
gmail_list_labels	List all Gmail labels/folders
gmail_draft	Create a draft email: plain text or rich HTML body, optional file attachments, optional reply-in-thread via thread_id (does NOT send)
gmail_create_label	Create a new label (supports nesting with /)
gmail_apply_label	Apply a label to one or more messages
gmail_remove_label	Remove a label from one or more messages
gmail_create_filter	Create a filter rule (match criteria → actions)
gmail_move_to_delete	Soft-delete: move messages to a "To Be Deleted" label
gmail_list_drafts	List current drafts with IDs, subjects, recipients, thread
gmail_update_draft	Revise a draft in place, preserving its thread and threading headers
gmail_delete_draft	Remove a draft. Trash by default (30-day recovery), permanent on request

Calendar (7 tools)

Tool	Description
calendar_list	List upcoming calendar events
calendar_search	Search events by keyword
calendar_get	Get full details of a specific event
calendar_create	Create an event (does NOT send invites by default)
calendar_update	Modify an existing event (does NOT notify attendees by default)
calendar_flag_delete	Soft-delete: prepend "DELETE - " to event title
calendar_availability	Check free/busy status for a date range

Contacts (2 tools)

Tool	Description
contacts_search	Search contacts by name, email, or phone
contacts_list	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
config.json	Account registry (names, email hashes, defaults)
tokens/<hash>.json	OAuth tokens per account (auto-refreshed)
action-log.jsonl	Append-only log of all mutations

Tokens are stored by email hash, not plaintext email, for a layer of indirection.

Action Log

Every write operation (drafts, 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'"}

The log is append-only and never modified by the server. Review it anytime to audit what Claude has done.

Fork and Use

To use this with your own Google account:

1. Fork this repo
2. Create your own Google Cloud project and OAuth credentials (see Setup above)
3. Build and point your Claude Code config at your fork's dist/index.js
4. Run google_auth to authenticate

No code changes needed. All account-specific data lives in config files and environment variables.

Tech Stack

• TypeScript
• @modelcontextprotocol/sdk: MCP protocol implementation
• googleapis: Google API client
• google-auth-library: OAuth2 token management
• zod: Input validation

License

MIT