Skip to main content
Glama
fernandezdiegoh

gmail-mcp

by fernandezdiegoh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

gmail-mcp

Minimal Gmail MCP server for Claude Code. Zero third-party code — only official Google and Anthropic libraries.

Tools

Tool

Description

search_emails

Search with Gmail query syntax (is:unread, from:x, after:2026/03/01)

read_email

Read full email by ID (headers + plain text body, HTML fallback)

read_thread

Read all messages in a thread

mark_as_read

Mark one or more emails as read

mark_as_unread

Mark one or more emails as unread

send_email

Send email (to, cc, bcc, subject, body)

create_draft

Create draft without sending

reply

Reply to a thread (supports reply-all)

list_labels

List all labels with unread counts

Related MCP server: gmail-mcp

Architecture

gmail-mcp/
├── server.py          # FastMCP server — 9 tools, stdio transport
├── auth.py            # OAuth2 flow + credential management
├── gmail_tools.py     # Gmail API wrapper functions
├── requirements.txt   # 3 dependencies (all official)
├── setup.sh           # Create venv + install + first-time OAuth
├── .env.example       # Template for OAuth credentials
└── .gitignore

  • Transport: stdio (standard for Claude Code MCPs)

  • Auth: OAuth2 with gmail.modify scope (covers read + modify + send)

  • Multi-account: Two instances in ~/.claude.json with different env vars

  • Token storage: ~/.gmail-mcp/{email}.json per account, 0600 permissions

Setup

1. Google Cloud Console

  • Enable the Gmail API in your GCP project

  • Create an OAuth 2.0 Client ID (Desktop application)

  • Add https://www.googleapis.com/auth/gmail.modify to allowed scopes

2. Install

git clone https://github.com/fernandezdiegoh/gmail-mcp.git
cd gmail-mcp
cp .env.example .env
# Edit .env with your OAuth credentials
bash setup.sh

setup.sh creates the venv, installs deps, and runs the browser OAuth flow.

3. Register in Claude Code

Add to ~/.claude.json under "mcpServers":

"gmail": {
  "type": "stdio",
  "command": "/path/to/gmail-mcp/.venv/bin/python3",
  "args": ["/path/to/gmail-mcp/server.py"],
  "env": {
    "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
    "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
    "USER_EMAIL": "you@example.com",
    "CREDENTIALS_DIR": "~/.gmail-mcp"
  }
}

Multi-account

Register multiple instances with different keys (e.g., gmail and gmail-personal) pointing to the same server.py but different env vars. Each account gets its own token file in CREDENTIALS_DIR.

Dependencies

Package

Purpose

Source

mcp

MCP SDK (FastMCP)

Anthropic (official)

google-auth-oauthlib

OAuth2 flow

Google (official)

google-api-python-client

Gmail API client

Google (official)

Requirements

  • Python 3.10+

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-gmail

    knowledgeislands
    A
    license
    B
    quality
    F
    maintenance
    MCP server that connects Claude with Gmail to read, send, delete, and manage messages and labels via the Google Gmail API.
    3
    MIT

  • Gmail MCP Server

    stevesimpson418
    A
    license
    Not graded
    quality
    C
    maintenance
    A local MCP server that provides tool-level access to Gmail, allowing Claude to search, read, send, and manage emails using the Gmail API.
    1
    MIT

  • advanced-gmail-mcp

    coreyepstein
    A
    license
    Not graded
    quality
    D
    maintenance
    A Gmail MCP server for Claude Code that enables full email management across multiple Gmail accounts, including tools for listing, searching, reading, sending, and organizing emails with OAuth2 authentication.
    89 npm
    7
    MIT