gmail-writer

A local MCP server that gives Claude working Gmail write operations: because the hosted Gmail MCP's write tools are broken by design.

The bug this fixes

The claude.ai hosted Gmail MCP shows write tools (label_thread, unlabel_thread, …) but every call fails with "insufficient authentication scopes". Root cause, found the hard way: the hosted MCP has a tool cap during OAuth negotiation, and under it it only requests gmail.readonly: never gmail.modify. The write tools are advertised but can never work. This server sidesteps the whole path: a local MCP process with its own Desktop OAuth client requesting the correct scope.

Tools

Tool	Description
gmail_modify_thread	Add/remove labels on a thread: move, archive, star, mark read/unread
gmail_search_threads	Search threads with Gmail query syntax
gmail_list_labels	List all labels with IDs
gmail_list_attachments	Find attachments across messages matching a query (metadata only)
gmail_download_attachment	Download one attachment by ID
gmail_download_all_attachments	Bulk-download every attachment matching a query, foldered per email

Also included: label-for-deletion.mjs, a standalone script that applies a review label to inbox junk matching your queries (edit the QUERIES array; set GMAIL_DELETION_LABEL_ID) so you bulk-delete from the Gmail UI with one filtered view.

Setup

1. In Google Cloud Console: create a project, enable the Gmail API, create a Desktop app OAuth client.
2. Run any google-auth-oauthlib installed-app flow with scope https://www.googleapis.com/auth/gmail.modify and write the result to ~/.gmail_token.json as {client_id, client_secret, token, refresh_token, expiry}: the file is self-contained and the server refreshes it automatically.
3. npm install, then register with Claude Code:

claude mcp add gmail-writer -- node /path/to/gmail-writer/index.js

4. node test.js runs the read-only test suite against your mailbox.

Security notes

The token file grants mail write access: keep it out of any repo (chmod 600, never commit). The server runs locally and talks only to Google's API; nothing is proxied through third parties.

Licence

MIT.