# 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 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](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](https://console.cloud.google.com/)
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

```bash
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`:

```json
{
  "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 |
| `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) |
| `actions.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/actions.jsonl` in this format:

```json
{"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