Skip to main content
Glama
grtelfer

gmail-attachments-mcp

by grtelfer
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

Related MCP server: Gmail MCP Server

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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • sudo-mcp-gmail

    sahilyadav902
    A
    license
    -
    quality
    D
    maintenance
    An MCP server for Gmail that allows AI assistants to read, search, compose drafts, send emails, and manage labels with attachment support.
    Last updated
    MIT

  • Gmail MCP Server

    nasirhuss86
    A
    license
    -
    quality
    D
    maintenance
    A custom MCP server for sending and managing Gmail emails, supporting both App Password and OAuth2 authentication with features like template emails and label listing.
    Last updated
    200
    MIT

  • multi-gmail-mcp

    joewhaley
    A
    license
    -
    quality
    C
    maintenance
    An MCP server that provides read, label, and draft access to multiple Gmail accounts from a single server, never sending email.
    Last updated
    83
    MIT

  • gmail-fast-mcp

    jeffmm
    F
    license
    -
    quality
    D
    maintenance
    A Gmail MCP server providing 19 tools for email operations, label and filter management, and attachment handling via the Gmail API.
    Last updated

View all related MCP servers

Related MCP Connectors

  • MCP Emails

    Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.

  • Gmail

    Gmail MCP Pack

  • PlanExe

    MCP server for generating rough-draft project plans from natural-language prompts.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/grtelfer/gmail-attachments-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server