# personal-gmail-mcp

> A read-only Gmail connector for Claude Code. One OAuth scope, a refresh token in the macOS Keychain, and email the agent treats as data.

Canonical: https://mark-web.com/projects/personal-gmail-mcp
Author: Mark Sulleza
Stack: TypeScript, MCP over stdio, Google OAuth with PKCE, macOS Keychain
Source: https://github.com/mSulleza/personal-gmail-mcp
Write-up: https://mark-web.com/writing/read-only-gmail-mcp

## Set it up (about ten minutes, once)

In a browser signed in to the personal Google account:

1. Create a Google Cloud project and enable the Gmail API.
2. Set up the consent screen: External, your own address as a test user, and one scope, `gmail.readonly`.
3. Create an OAuth client of type **Desktop app**, download its JSON, and put it at `~/.config/personal-gmail-mcp/client_secret.json` (mode 600).
4. Sign in:

```bash
npm run login
```

Google warns that it hasn't verified the app; that's expected for your own. The refresh token goes into the macOS Keychain, not a file.

5. Register it with Claude Code for every project:

```bash
claude mcp add -s user personal-gmail -- "$(which node)" \
  ~/personal/personal-gmail-mcp/node_modules/tsx/dist/cli.mjs \
  ~/personal/personal-gmail-mcp/src/index.ts
```

## Use it

Ask in plain words: "find last month's card statement and save the PDF", "when is the dentist appointment". Claude Code calls `search_threads` with Gmail search syntax, reads the thread with `get_thread`, and saves attachments with `save_attachment` into `~/Downloads/personal-gmail/<message id>/`, never overwriting a file.

Every piece of email content comes back in fields marked `data_text`, and the agent is told to read those as data, never as instructions. Anyone can send you an email.

## Stop it

```bash
npm run logout
```

That revokes the sign-in at Google and removes the token from the Keychain. Access can also be revoked at myaccount.google.com/connections.

## The tests

The suite at the top of this page covers the read-only scope, MIME and HTML parsing, the OAuth URL, PKCE and the loopback state check, token refresh, every tool against a fake Gmail API, safe attachment names, and the server over stdio.