Skip to main content
Glama
gmail-read-mcp

gmail-read-mcp

by gaberogan

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

Available Tools

2 tools
list_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

    A4.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Gmail, enabling email search, unread listing, message and thread retrieval, and draft reply preparation without sending.
      239 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables searching and reading Gmail messages, listing labels, and creating email drafts without sending or deleting emails.
      298 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only Gmail access via MCP, allowing users to list and retrieve email messages with query and pagination support.
      4
      MIT