gmail-attachments-mcp

An MCP server that gives Claude the two Gmail capabilities most built-in Gmail connectors lack: downloading attachments and creating drafts with file attachments.

Runs locally. Talks only to your own mailbox. Cannot send email.

Why this exists

Most hosted Gmail integrations are metadata-only. They can tell you an email has a PDF attached; they cannot hand you the PDF, and they cannot attach a file to a draft. That makes a large class of ordinary work impossible: reading an invoice someone emailed you, or replying to a request with a document attached.

This server closes that gap and nothing else.

Tools

Tool	What it does
gmail_search_messages	Search with Gmail query syntax; returns messages plus attachment metadata
gmail_list_attachments	List every attachment on one message (filename, mimeType, size, attachmentId)
gmail_download_attachment	Save one attachment, or all of them, to a local folder
gmail_create_draft_with_attachments	Create a draft with file attachments. Saved, never sent.
gmail_apply_label	Add or remove labels on a message. Creates missing labels, including nested names.

One gotcha worth knowing

Gmail does not guarantee that attachmentId values stay stable across separate API calls. The same attachment can report a different id seconds later. Always pass filename to gmail_download_attachment rather than attachmentId. The tool re-resolves the id internally.

Install

Requires Node.js 18 or later.

git clone https://github.com/grtelfer/gmail-attachments-mcp.git
cd gmail-attachments-mcp
./install.sh

The installer checks prerequisites, installs dependencies, builds, registers the server with Claude Code, and walks you through authorization.

You need your own Google OAuth client first. See SETUP-GOOGLE-CLOUD.md. It works with a personal @gmail.com account; Google Workspace is not required. Budget ten minutes, once.

The one thing people get wrong: if you leave the OAuth consent screen in Testing status, Google expires your refresh token every seven days and the server silently stops working. Publishing the app removes the expiry and takes one click. Step 5 of the setup guide covers it.

Manual install

If you would rather not run the script:

npm install
npm run build
claude mcp add gmail --scope user -- node "$PWD/dist/index.js"
npm run auth

Then restart Claude Code. Tools appear as mcp__gmail__*.

Registering the server under the name gmail is what produces the mcp__gmail__ prefix. Pick a different name if you prefer, but any skills referring to these tools will need updating to match.

Verify it works

Restart Claude Code, then ask:

find my most recent email with an attachment and download it

Configuration

Variable	Effect
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Supply OAuth credentials via environment instead of credentials.json
GOOGLE_MCP_PROFILE	Namespace the stored token, so you can authorize multiple Google accounts side by side. Alphanumeric, hyphens, and underscores only.
XDG_CONFIG_HOME	Overrides where the token is stored. Defaults to ~/.config/gmail-mcp/.

Security

• Never commit credentials.json or token.json. Both are in .gitignore.
• The token file is written with mode 0600 and holds only a refresh token.
• Scopes are gmail.modify and gmail.compose. There is no send scope, so the server cannot send mail on your behalf. Drafts wait for you.
• Everything runs on your machine. No data leaves it except calls to Google's own API.
• To revoke access at any time, go to https://myaccount.google.com/permissions and remove the app.

Optional: the Claude skill

SKILL.md is an Agent Skill that teaches Claude the common workflows: reading an attachment somebody sent you, and replying with a file attached. Copy it into ~/.claude/skills/gmail-attachments/ to install it, or ignore it and use the tools directly.

License

MIT. See LICENSE.