gmail-read-mcp
Provides read-only access to a Gmail mailbox, allowing listing emails by date range with metadata and snippet, reading full email headers and body text, and generating deep links to jump directly to emails.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-read-mcp list emails from the past week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Create a Google Cloud project (separate from any production project — the consent screen is per-project) and enable the Gmail API.
Set the OAuth consent screen to Internal (skips restricted-scope verification for the
gmail.readonlyscope).Create an OAuth client of type Desktop app and download the client JSON.
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 startTesting
npm testAvailable Tools
2 toolslist_emailsList emailsA
List emails received in a date range: metadata + snippet, oldest-first, capped at 500 with no truncation flag. Spam and trash are excluded. Mail sent from the mailbox itself (i.e. the team's replies) is excluded unless include_sent is true. Each result has a jump_url deep link that opens the email for anyone signed into the mailbox. Use read_email for the full body.
Inputs: end_time (required), start_time (required), query, include_sent.
read_emailRead an emailA
Read one email by id (from list_emails): full headers and body text (HTML converted to text, capped at 50k chars).
Inputs: id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools, list_emails and read_email, have clearly distinct purposes—one for enumerating emails and the other for fetching full details of a specific email. There is no overlap or confusion possible.
Both tool names follow the consistent verb_noun pattern: 'list_emails' and 'read_email'. The naming is predictable and aligns with the server's read-only scope.
With only two tools, the server is minimal but well-suited for a read-only Gmail interface. While the count feels thin relative to typical multi-purpose servers, the narrow scope justifies the small surface.
For a read-only mail server, the two tools cover the core workflow: listing emails with metadata and reading a full email by ID. There are no apparent gaps that would impede an agent from retrieving email data.
Related MCP Connectors
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables reading, sending, archiving, and managing Gmail emails and labels through Google OAuth authentication, acting as an OAuth proxy to the Gmail API.239 npm12MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Gmail, enabling email search, unread listing, message and thread retrieval, and draft reply preparation without sending.239 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables searching and reading Gmail messages, listing labels, and creating email drafts without sending or deleting emails.298 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only Gmail access via MCP, allowing users to list and retrieve email messages with query and pagination support.4MIT