Gmail Attachments MCP server

gmail-attachments-mcp

<!-- mcp-name: io.github.zayansalman/gmail-attachments-mcp -->

A focused Model Context Protocol server (and standalone CLI) for downloading Gmail attachments to disk. Three tools, read-only OAuth scope, no extra surface area.

Built because the hosted claude.ai Gmail connector in Claude Desktop returns attachment IDs and metadata only — not the actual bytes. This server fills that gap for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.), and also works as a plain CLI for cron jobs and shell scripts.

If you used @GongRzhe/Gmail-MCP-Server (1.1k★, archived 2026-03-03) for its attachment-download workflow, this is a minimal successor focused on that single capability.

Features

• 3 MCP tools — gmailsearch, gmaildownloadthreadattachments, gmaildownloadlatest_matching. That's the whole API.
• Read-only OAuth scope (gmail.readonly) — can't send, delete, or modify mail.
• Works as both an MCP server and a standalone CLI — same code, same auth token, both surfaces.
• Env-var-driven config — GMAILMCPCREDENTIALS, GMAILMCPTOKEN, GMAILMCPDEFAULTDESTDIR.
• Cron-friendly — once authorized, the cached refresh token lets headless jobs run indefinitely.

Install

pip install gmail-attachments-mcp
# or, with uv:
uv tool install gmail-attachments-mcp

One-time setup (~10 minutes)

You need a Google Cloud OAuth client. The server runs entirely on your machine; nothing leaves it.

1. Sign in to Google Cloud Console with the Gmail account whose attachments you want to download.
2. Create a project (or pick an existing one).
3. Enable the Gmail API: console.cloud.google.com/apis/library/gmail.googleapis.com.
4. Configure the OAuth consent screen under APIs & Services → OAuth consent screen:

• Google Workspace users: User type = Internal (no app verification needed).
• Personal Gmail users: User type = External. Add your own Gmail address as a test user under "Test users".

1. APIs & Services → Credentials → + Create credentials → OAuth client ID

• Application type: Desktop app
• Download the JSON.

1. Run setup:

gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json

A browser window opens for OAuth consent. After consent, a refresh token is cached at ~/.config/gmail-attachments-mcp/token.json (or $XDGCONFIGHOME/gmail-attachments-mcp/).

Verify:

gmail-attachments-mcp status
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3

See docs/setup-google-oauth.md for screenshots and troubleshooting.

Use it from Claude Code

claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve

Then in any Claude Code session:

Use the gmail-attachments MCP to download the latest CV from careers@example.com to ~/CVs.

Use it from Claude Desktop

Edit ~/Library/Application Support/Claude/claudedesktopconfig.json (Mac) or %APPDATA%/Claude/claudedesktopconfig.json (Windows):

{
  "mcpServers": {
    "gmail-attachments": {
      "command": "gmail-attachments-mcp",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. See docs/claude-desktop.md for details.

Use it from Cursor / Cline / Continue / others

Any MCP client that supports stdio servers. Point it at the same gmail-attachments-mcp serve command. See docs/other-clients.md.

Use it from the shell or cron

# Search
gmail-attachments-mcp search "from:noreply@stripe.com has:attachment newer_than:30d"

# Download every attachment from a specific thread
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices

Shortened. The full README is on GitHub.