gmail-attachments-mcp

Give your AI agent the ability to open Gmail attachments.

Most Gmail integrations let an agent search and read email bodies but stop at the attachment. This MCP server fills that gap. Your agent can list what is attached to a message, read PDFs, Word, Excel and PowerPoint files straight into its context, or save any attachment to disk. Read-only (gmail.readonly). Runs locally on your machine, or hosted on Vercel for yourself or a small allowlist of people.

Works with any MCP client: Claude Code, Claude Desktop, Cursor, and others.

What your agent can do with it

• "Summarise the PDF the recruiter sent me."

• "Read the invoice attached to that Anthropic email and check the totals match the email body."

• "Pull the job description from the latest email and compare it to my CV."

• "Download the spreadsheet from Sam's email and total column C."

• "List every attachment in that thread."

Pair it with a Gmail connector: the connector finds the message and gives the message_id, this server opens the attachments.

Related MCP server: Gmail AutoAuth MCP Server

Tools

• list_attachments(message_id): name, type, size

• download_attachment(message_id, filename, dest_dir="", index=0): saves to ~/Downloads/gmail-attachments by default, never overwrites

• get_attachment_base64(message_id, filename, index=0): returns raw file bytes as base64 so a client can write them to disk (works on the hosted server; refuses files over ~1.5 MB)

• read_attachment_text(message_id, filename, index=0, max_chars=20000): extracts text without saving the file. Supported types:

  • PDF (text-based; scanned PDFs return a hint to download instead)

  • Word .docx (paragraphs and tables)

  • Excel .xlsx (every sheet, rows joined with |)

  • PowerPoint .pptx (text per slide)

  • Plain text: .txt, .csv, .json, .xml, .html, .md

  • Anything else (images, zip, legacy .doc / .xls / .ppt): use download_attachment, then open the file yourself.

message_id is the same id the Gmail connector returns from search_threads / get_message.

One-time setup

1. Google Cloud Console: create a project, enable the Gmail API.

2. OAuth consent screen: External, add your Gmail as a test user.

3. Credentials: create an OAuth client ID, type Desktop app. Download the JSON.

4. Save it as ~/.config/gmail-attachments-mcp/credentials.json (outside the repo).

5. Authorise once (opens a browser):

   uv run gmail-attachments-auth

   Token is saved to ~/.config/gmail-attachments-mcp/token.json (mode 600).

Install in your agent

Clone the repo first (needs uv):

git clone https://github.com/savestidolajr/gmail-attachments-mcp

Claude Code

claude mcp add gmail-attachments --scope user -- uv run --directory /absolute/path/to/gmail-attachments-mcp gmail-attachments-mcp

Claude Desktop, Cursor and other MCP clients: add this to the client's MCP config (claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "gmail-attachments": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/gmail-attachments-mcp", "gmail-attachments-mcp"]
    }
  }
}

Restart the client, then ask it to list the attachments on any email.

Host it on Vercel (use from any device)

The local server only works on the machine it runs on. Hosted mode runs the same tools over streamable HTTP, protected by a bearer token, as a Vercel Python service. It has no download_attachment (no persistent disk) and takes credentials from env vars instead of token.json. app.py exposes the ASGI app, vercel.json declares it as a service and routes everything to it. The MCP session runs per request (stateless, JSON responses), so it does not depend on lifespan events.

If DATABASE_URL is not set, the server runs in owner-only mode: the static MCP_AUTH_TOKEN is the only credential, there are no OAuth routes (they return 404), and everything below works as written. Setting DATABASE_URL switches on multi-user mode (next section), which then requires four more variables.

1. Do the one-time Google setup and uv run gmail-attachments-auth locally.

2. npm i -g vercel, then vercel login.

3. ./scripts/vercel-setup.sh links the project and sets the four env vars from your local OAuth files, piped straight to Vercel. It prints the generated MCP_AUTH_TOKEN once. Save it.

4. vercel deploy --prod

5. Connect your client to https://<your-project>.vercel.app/mcp. For Claude Code:

   claude mcp add --transport http gmail-attachments https://<your-project>.vercel.app/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Which clients can connect to the hosted server

In single-token mode the server accepts Authorization: Bearer <MCP_AUTH_TOKEN>, so the client must be able to send that custom header. In multi-user mode (below) clients sign in with OAuth instead and do not need to send a custom header.

To add it on another machine, run the claude mcp add --transport http ... command above with the same token.

In owner-only mode the server reads one Gmail account: whoever owns the refresh token in its env vars. In multi-user mode (below) each person signs in with their own Google account and only ever sees their own mail.

To rotate the token later and re-register it in Claude Code in one step, with the token never printed: ./scripts/rotate-and-register.sh.

Caveats: the default function time limit applies to large attachments, cold starts import the Google and Office libraries, and Vercel's deployment protection may block the URL until you disable it for this project. Security (single static-token setup): anyone with the bearer token can read attachments in the Gmail account. Keep the token secret, keep the scope read-only, rotate MCP_AUTH_TOKEN if it leaks, and do not hand that token to other people. To share with others, use "Multi-user hosted mode (allowlist)" below, with its stated limits. In multi-user mode, OAuth-issued access tokens are also accepted on /mcp. Without a token of 32+ characters the server rejects every request. /health is the only unauthenticated route.

Multi-user hosted mode (allowlist)

The hosted server is also an OAuth 2.1 server. Someone you approve adds your connector URL, signs in with Google once, and then their MCP client can list and read their own attachments. Works in Claude web, mobile, Desktop and Code.

How it works: the MCP SDK provides the OAuth endpoints; the server stores each user's Google refresh token encrypted (AES-GCM) in Postgres, issues its own short-lived MCP tokens (1 hour access, 30 day rotating refresh, stored as hashes), and checks the signed-in Google email against an allowlist. Every Gmail call uses the caller's own token. Your static MCP_AUTH_TOKEN still works as the owner.

Limits to know about:

• While your Google OAuth app is in "Testing", Google expires each user's refresh token after 7 days. They get a "reconnect" error, then sign in again. Up to 100 test users.

• You hold access to every approved user's mail. Only approve people you trust and keep the database and TOKEN_ENC_KEY safe.

• The reliable way for a user to disconnect is to remove the app at myaccount.google.com/permissions. Their next tool call then fails to refresh, the server wipes the stored token, and the client has to sign in again. /revoke also disconnects, but some public clients cannot call it.

• Making this public for anyone needs Google restricted-scope verification and an annual third-party security assessment. Not done.

Offboarding someone:

• Removing an email from the allowlist only blocks new sign-ins. To cut off someone who is already connected, disconnect them too. Run this in the Neon SQL editor or psql (the allowlist delete comes first so they cannot sign back in mid-way), replacing friend@gmail.com (addresses are stored lowercase):

  BEGIN;
  DELETE FROM allowlist WHERE email = lower('friend@gmail.com');
  UPDATE mcp_tokens SET revoked_at = extract(epoch from now())
    WHERE user_id = (SELECT id FROM users WHERE email = lower('friend@gmail.com')) AND revoked_at IS NULL;
  UPDATE users SET google_refresh_token_enc = NULL, revoked_at = extract(epoch from now())
    WHERE email = lower('friend@gmail.com');
  COMMIT;

• The address must match exactly what Google reports for that account (dots included) and is stored lowercase. Check SELECT email FROM users; if unsure.

• They can also remove the app at myaccount.google.com/permissions to revoke Google's side.

Setup (once). Set all env vars before you deploy: with DATABASE_URL set but the others missing, every route except /health returns 500 listing what is missing. Also check whether the Vercel project auto-deploys from Git before you merge this branch to main, so it does not go live half-configured.

1. Postgres: Vercel dashboard, Storage, create a Neon database and connect it to the project. This adds DATABASE_URL.

2. Google OAuth client: in Google Cloud, create an OAuth client of type Web application with redirect URI https://<your-project>.vercel.app/google/callback. Keep the consent screen on Testing and add each user's Gmail as a test user.

3. Env vars (Vercel, production): PUBLIC_BASE_URL (https://<your-project>.vercel.app, no trailing slash; add it with --no-sensitive, Vercel does not allow PUBLIC* variables to be sensitive), GOOGLE_WEB_CLIENT_ID, GOOGLE_WEB_CLIENT_SECRET, TOKEN_ENC_KEY. Generate the key without printing it:

   python3 -c "import os,base64;print(base64.urlsafe_b64encode(os.urandom(32)).decode())" | vercel env add TOKEN_ENC_KEY production

   Rotating or losing this key disconnects every user on their next call (their stored token can no longer be decrypted), and they must reconnect. There is no dual-key support. Optional: MCP_ALLOWED_REDIRECT_URIS (see "Redirect URI allowlist" below). PUBLIC_BASE_URL must exactly equal the host Claude connects to. Load the Google client ID and secret straight from the JSON you downloaded (no copy and paste, nothing printed), then delete or move that file:

   F=~/Downloads/client_secret_XXXX.json   # must start with {"web": ...}, not "installed"
   python3 -c "import json,sys;sys.stdout.write(json.load(open(sys.argv[1]))['web']['client_id'])" "$F" | vercel env add GOOGLE_WEB_CLIENT_ID production --sensitive
   python3 -c "import json,sys;sys.stdout.write(json.load(open(sys.argv[1]))['web']['client_secret'])" "$F" | vercel env add GOOGLE_WEB_CLIENT_SECRET production --sensitive

4. Create tables and add people. vercel env pull cannot read sensitive variables (it writes the literal [SENSITIVE]), and the Neon DATABASE_URL is sensitive. Copy the connection string from the Neon dashboard (Connect), then in a real terminal tab (not a tool that runs each command in a fresh shell, or the variable is gone before the next line):

   read -s DATABASE_URL && export DATABASE_URL      # paste, press Enter (nothing is echoed)
   uv run gmail-attachments-initdb
   uv run gmail-attachments-allow you@gmail.com friend@gmail.com
   unset DATABASE_URL

   Addresses are stored lowercase and must match what Google reports. Do not use the Neon SQL editor for the schema: it runs each paste as one prepared statement and rejects the multi-statement script. It is fine for single statements such as the allowlist insert or the offboarding SQL below.

5. In Vercel, turn Deployment Protection off for the production domain. In multi-user mode Claude web cannot reach /.well-known/..., /register or /mcp otherwise.

6. vercel deploy --prod. Then add https://<your-project>.vercel.app/mcp as a custom connector in Claude.

Redirect URI allowlist

Client registration is open, so the server only accepts clients whose redirect URIs are on an allowlist (otherwise anyone could register a callback they control and phish an approved user through the real Google consent screen). Allowed: https://claude.ai/api/mcp/auth_callback, https://claude.com/api/mcp/auth_callback, loopback http://localhost, http://127.0.0.1 and http://[::1] on any port and path (CLI and desktop clients), and any URI listed exactly in MCP_ALLOWED_REDIRECT_URIS (comma-separated). If a client's registration is rejected with invalid_redirect_uri, add its callback URL to that variable and redeploy.

Verify after deploying

curl -s https://<your-project>.vercel.app/health                                   # ok
curl -s https://<your-project>.vercel.app/.well-known/oauth-authorization-server   # JSON, not a Vercel login page
curl -si -X POST https://<your-project>.vercel.app/mcp -H 'Content-Type: application/json' -d '{}' | grep -i www-authenticate   # points at the protected-resource metadata
curl -s -X POST https://<your-project>.vercel.app/register -H 'Content-Type: application/json' \
  -d '{"redirect_uris":["https://evil.example/cb"],"token_endpoint_auth_method":"none","grant_types":["authorization_code","refresh_token"],"response_types":["code"]}'   # 400 invalid_redirect_uri

Your owner connector (static MCP_AUTH_TOKEN) keeps working after the deploy. If the project is not linked to GitHub, pushing does not deploy; run vercel deploy --prod from the repo folder (vercel rollback undoes it).

First connect checklist

• Deployment Protection is off for the production domain.

• PUBLIC_BASE_URL equals the connector host exactly.

• Add the connector in Claude web (https://<your-project>.vercel.app/mcp).

• Sign in with a Google account that is on the allowlist (and a test user on the consent screen).

• Run a tool call, such as list_attachments.

• Expect the "reconnect" flow after 7 days while the Google app is in Testing mode.

Housekeeping

Expired tokens and old audit rows are not purged automatically. Run this occasionally in the Neon SQL editor (timestamps are epoch seconds). The Neon free tier has a small storage limit, so keep audit_log trimmed; change 90 days to the retention you want:

DELETE FROM mcp_tokens
  WHERE (expires_at < extract(epoch from now()) - 86400)
     OR (revoked_at IS NOT NULL AND revoked_at < extract(epoch from now()) - 86400);
DELETE FROM auth_codes
  WHERE used_at IS NOT NULL OR expires_at < extract(epoch from now());
DELETE FROM audit_log WHERE ts < extract(epoch from now()) - 90 * 86400;

Run the tests with uv run pytest. To include the Postgres tests, start a throwaway database and set TEST_DATABASE_URL:

docker run -d --name gmail-mcp-test-pg -e POSTGRES_PASSWORD=test -p 54329:5432 postgres:16
TEST_DATABASE_URL=postgresql://postgres:test@localhost:54329/postgres uv run pytest

Env vars

• GMAIL_ATT_CONFIG_DIR: where credentials/token live

• GMAIL_ATT_CLIENT_FILE: path to the OAuth client JSON

• GMAIL_ATT_DOWNLOAD_DIR: default download folder

• Hosted mode only: GMAIL_ATT_CLIENT_ID, GMAIL_ATT_CLIENT_SECRET, GMAIL_ATT_REFRESH_TOKEN, MCP_AUTH_TOKEN (set by scripts/vercel-setup.sh)

• Multi-user mode (switched on by setting DATABASE_URL; the other four are then required): DATABASE_URL, TOKEN_ENC_KEY, PUBLIC_BASE_URL, GOOGLE_WEB_CLIENT_ID, GOOGLE_WEB_CLIENT_SECRET; optional MCP_ALLOWED_REDIRECT_URIS (extra exact OAuth redirect URIs, comma-separated), GMAIL_ATT_RATE_LIMIT (calls per user per minute, default 60)

Notes

• While the OAuth app is in "Testing", Google expires the refresh token after 7 days. Re-run the auth command, or publish the app to "In production" (no verification needed for personal use of a single account).

• Never commit credentials.json or token.json. .gitignore covers both.

Privacy

Runs locally. Uses only the read-only Gmail scope. Your OAuth client and token stay on your machine in ~/.config/gmail-attachments-mcp/. Each user must create their own Google Cloud OAuth client. In multi-user hosted mode the operator's database holds each approved user's encrypted Google refresh token and an audit log of tool calls (tool name and message ID only, never attachment content).

Licence

MIT