v0.5.1

Documentation-only release.

• Tool descriptions now state what each tool reads, what it changes, what cannot be undone and which tool to consult first (list_accounts, list_labels, list_filters, create_label, delete_filter).
• Every parameter now has a description.
• No behavior changes; npm package and MCP registry entry updated to 0.5.1.

v0.5.0

New

• list_drafts and update_draft: edit an existing draft instead of piling up copies. Only the fields you pass change; the thread it answers and its current attachments stay (keep_attachments: false drops them).
• get_thread: a whole conversation, oldest first, by thread ID or the ID of any message in it. Quoted history inside replies is trimmed, and each message gets the same security notes as get_email.
• search_all_accounts: one Gmail search across every connected account, grouped by account.
• newsletters: mailing lists by volume (with unread counts) and the unsubscribe link each one declares, flagging one-click support and links on another domain. It only reports; it never unsubscribes for you.

Robustness

• Searches and big scans fetch ten messages at a time and back off when Gmail returns a quota error, so a large mailbox slows the scan down instead of breaking it.

Still no tool that sends, deletes or unsubscribes.

v0.4.0

New

• create_draft can attach local files (attachments: a list of paths). The draft is still never sent.

Security

• Only files under Downloads, Desktop or Documents can be attached (or the folders in GMAIL_TIDY_ATTACH_DIRS), never hidden folders or this server's own config. Links are resolved before the check, so a shortcut can't point at ~/.ssh.
• Attached file names are recorded in the audit log. Up to 24 MB per draft.

Fixes

• File names with accents now show correctly in Gmail.

v0.3.0

New

• recent_changes: every change this server made (labels, archiving, filters, drafts, signature, saved files) is appended to a private local audit.log, without message bodies, draft text or signatures. If a session did something odd, you can see exactly what and undo it.
• Lookalike senders: a domain one or two letters away from one of your connected accounts, or one that uses letters from other scripts that look Latin, gets a security note. For Gmail and other webmail the mailbox name is compared. Mail between your own accounts is never flagged.

Quieter on real mail

• A Reply-To pointing to free webmail only counts when the sender fails DMARC (payment platforms legitimately route replies to the shop).
• Links to loopback and private IPs are ignored (development mail).

Calibrated against 120 real messages across three accounts: no false alarms.

v0.2.0

New tools

• get_attachment: text, .gz and .zip attachments are read inline (DMARC reports, CSV, XML). Anything else, like a PDF, is saved to ~/Downloads/gmail-tidy-mcp. get_email now lists attachments with their part number.
• sender_stats: who sends the most mail for a search, by address and by domain.
• update_label: rename, recolor (Gmail palette) and show or hide a label in the sidebar or message list. Replaces set_label_color.
• set_signature: changes only the signature, never how mail goes out.

Security

• Invisible text (Unicode tag characters, zero-width and text-direction controls) is stripped from headers, bodies and attachments; tag characters are reported.
• get_email and get_attachment add security notes written by the server, outside the untrusted block: prompt-injection phrasing, SPF/DKIM/DMARC failures, a Reply-To pointing to free webmail, display-name spoofing, and links whose text and destination disagree (Gmail and Outlook redirects are unwrapped; tracking links in mailing lists are not flagged).
• Executables, disguised names (invoice.pdf.exe, right-to-left tricks), files whose bytes don't match the extension, and archives containing them are not saved unless allow_risky: true. Password-protected archives, macro-enabled Office files and PDFs with JavaScript or auto-run actions are flagged. Saved files never overwrite anything and get the macOS quarantine flag.

Still no tool that sends or deletes mail.

v0.1.1

First public release.

gmail-tidy-mcp lets your AI assistant read and organize several Gmail accounts at once, and it can never send or delete mail.

What's in it

• Connect any number of accounts and refer to them by a short label.
• Search and read mail with Gmail's search syntax.
• Create labels, relabel and archive mail by ID or by search (up to 5,000 messages at a time).
• Create, list and delete filters.
• Write drafts, including replies inside a thread. You send them yourself.

Safety

• No tool sends, replies, forwards or deletes mail, and a test fails if any such call appears in the code.
• Trash and Spam can't be added, and filter actions are limited to label changes.
• Tokens are encrypted with AES-256-GCM, with the key in the macOS Keychain, the Linux Secret Service or DPAPI on Windows.
• Sign-in uses PKCE and a random state, and the signed-in account and granted scopes are verified before anything is saved.
• Email content reaches the model inside a nonce-fenced untrusted block, with hidden HTML text removed.

Install

claude mcp add -s user gmail-tidy -- npx -y gmail-tidy-mcp

See the README for creating your own Google OAuth client.