Gmail日历联系人MCP服务器

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

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

Gmail (12 tools)

Calendar (7 tools)

Contacts (2 tools)

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/:

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