# gmail-mcp

A read-only Gmail [MCP](https://modelcontextprotocol.io) server, built from scratch on the MCP SDK — no third-party Gmail MCP packages. Lets Claude Code (or any MCP client) search and read a Gmail inbox without ever being able to send, delete, or modify anything.

## Tools

| Tool | What it does |
|------|--------------|
| `list_emails` | Search the inbox with full [Gmail search syntax](https://support.google.com/mail/answer/7190) (`from:`, `newer_than:`, `has:attachment`, …), with a `maxResults` cap |
| `get_email` | Fetch a single message by id: headers plus the full plain-text body |

## Design notes

- **Read-only by construction.** The OAuth scope is `gmail.readonly` — the token Google issues cannot send or delete mail even if the server were compromised.
- **Google OAuth 2.0 Desktop-app flow.** A one-time `npm run auth` opens a browser for consent, then stores a refresh token locally. The server auto-refreshes access tokens and persists them back to disk, so auth survives restarts.
- **Secrets stay out of the repo.** `credentials.json` (OAuth client) and `token.json` (tokens) are gitignored; the code loads them from disk at startup.

## Setup

1. In Google Cloud Console, create a project, enable the Gmail API, and create an OAuth client of type **Desktop app**. Download it as `credentials.json` into this folder. While the consent screen is in Testing mode, add your address under Audience → Test users.
2. Install and authenticate:

   ```sh
   npm install
   npm run auth   # opens browser, writes token.json
   ```

3. Register with Claude Code (user scope makes it available in every session):

   ```sh
   claude mcp add gmail -s user -- node /absolute/path/to/gmail-mcp/index.js
   ```

   Verify with `claude mcp list` — the server should show as Connected.

## Files

- `index.js` — the MCP server (tool definitions, Gmail API calls, token refresh persistence)
- `auth.js` — one-time OAuth consent flow; writes `token.json`