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:

   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.

Related MCP server: Gmail MCP Server

Local setup

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

Testing

npm test