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.

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 anything. Gmail uses a "To Be Deleted" label (soft-delete). Calendar prepends "DELETE - " to event titles. You review and confirm in the Google UI.
• 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 (20)

Authentication & Status

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

Gmail (9 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