# gmail-read-mcp

Read-only Gmail MCP server scoped to a single mailbox. Exposes two tools over stdio:

- **list_emails** - list emails received in a date range: metadata + snippet, oldest-first (max 500)
- **read_email** - read one email's full headers and body text by id

No write, send, label, or delete capabilities. Every result carries a `jump_url`
deep link (`rfc822msgid:` search) that opens the email for anyone signed into
the mailbox. Mail sent from the mailbox itself (the team's replies) is excluded
by default; spam and trash are always excluded.

## Google OAuth setup

1. Create a Google Cloud project (separate from any production project — the
   consent screen is per-project) and enable the **Gmail API**.
2. Set the OAuth consent screen to **Internal** (skips restricted-scope
   verification for the `gmail.readonly` scope).
3. Create an OAuth client of type **Desktop app** and download the client JSON.
4. Run the one-time consent flow signed in as the target mailbox:

   ```sh
   node scripts/gmail-oauth-once.mjs <path-to-client-secret.json>
   ```

   It prints the refresh token and which mailbox it is bound to.

The refresh token has no expiry, but Google revokes Gmail-scope tokens when the
account password changes. If the server starts failing with `invalid_grant`,
re-run step 4 and replace `GMAIL_REFRESH_TOKEN`.

## Local setup

```sh
cp .env.example .env
# Fill in GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN
npm install
npm start
```

## Testing

```sh
npm test
```