GMAIL_MCP_CREDENTIALS — Path to the Google OAuth client secret JSON. Default: $XDG_CONFIG_HOME/gmail-attachments-mcp/credentials.json.
GMAIL_MCP_TOKEN — Path to the cached Gmail OAuth refresh token. Default: $XDG_CONFIG_HOME/gmail-attachments-mcp/token.json.
GMAIL_MCP_DEFAULT_DEST_DIR — Default directory where downloaded attachments are saved when the tool call does not specify dest_dir. Default: ~/Downloads.
GMAIL_MCP_SCOPES — Comma-separated Google OAuth scopes. Default: https://www.googleapis.com/auth/gmail.readonly.
Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
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.
Minimal MCP server for downloading Gmail attachments to disk. Read-only OAuth by default.
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.
A browser window opens for OAuth consent. After consent, a refresh token is cached at ~/.config/gmail-attachments-mcp/token.json (or $XDG_CONFIG_HOME/gmail-attachments-mcp/).
Verify:
gmail-attachments-mcp status
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3
Convenience: search + download from the single most recent match, in one call.
Configuration
All paths can be overridden via environment variables.
Variable
Default
What
GMAIL_MCP_CREDENTIALS
~/.config/gmail-attachments-mcp/credentials.json
OAuth client secret JSON
GMAIL_MCP_TOKEN
~/.config/gmail-attachments-mcp/token.json
Cached refresh token
GMAIL_MCP_DEFAULT_DEST_DIR
~/Downloads
Default download destination
GMAIL_MCP_SCOPES
https://www.googleapis.com/auth/gmail.readonly
OAuth scopes (comma-separated)
XDG_CONFIG_HOME
~/.config
Standard XDG override
Security
Token storage: refresh token is written to ~/.config/gmail-attachments-mcp/token.json with mode 0600. Anyone with shell access to your account can read your Gmail. Treat the file like a password.
OAuth scope: default is gmail.readonly. Cannot send, delete, or modify mail. If you change $GMAIL_MCP_SCOPES, you're on the hook for the consequences.
Credential file: your OAuth client secret JSON is not a password — it identifies your app to Google. But never commit it. The included .gitignore blocks the common filenames.
OAuth client: your client lives in your Google Cloud project. There's no central server, no telemetry, nothing leaves your machine.
Troubleshooting
No valid Gmail token when invoked from Claude Desktop / cron
The first OAuth flow requires a browser. Run gmail-attachments-mcp setup once in a terminal where a browser can open. Subsequent runs use the cached refresh token.
Token has been expired or revoked
Refresh tokens stay valid as long as you use them at least every 6 months and don't revoke them at myaccount.google.com/permissions. Re-auth:
gmail-attachments-mcp setup --reauth
Access blocked: This app's request is invalid
On personal Gmail, your OAuth consent screen needs your address listed under Test users. Workspace users should select Internal audience to avoid this.
HttpError 403: Request had insufficient authentication scopes
You changed $GMAIL_MCP_SCOPES without re-authorizing. Run gmail-attachments-mcp setup --reauth.
Pick this one if you want a tiny, focused, read-only tool. Pick a fuller one if you also need to send mail, manage labels, drafts, threads, etc.
Authentication — bring your own Google OAuth client
There are no API keys and no shipped secrets. The server authenticates to your Google account with an OAuth client you create, and caches a refresh token locally. The author has zero access to your data.
Why your own client? Google's restricted scopes (here, gmail.readonly) can't be redistributed in a shared app, and an unverified shared app is capped at 100 users. "Bring your own OAuth client" is the standard pattern for personal-data MCP servers.
What you need: a free Google Cloud project, the Gmail API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → docs/setup-google-oauth.md.
Where your token lives:~/.config/gmail-attachments-mcp/token.json (mode 0600). Delete it to revoke locally; revoke fully at myaccount.google.com/permissions.
No hosted/SaaS option — everything runs locally; your mail never touches a third-party server.
Related tools
Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
gmail-attachments-mcp — download Gmail attachment bytes to disk (this repo)