List the configured Gmail accounts (no secrets), showing which is default and which are read-only.

Search a Gmail account with native Gmail query syntax (e.g. 'from:alice newer_than:7d has:attachment', 'in:anywhere subject:invoice'). Returns summaries with gmMsgId/gmThrId. Note: All Mail excludes Trash/Spam unless you add 'in:anywhere'.

Fetch a full message: headers, plain-text and HTML bodies, and attachment metadata (use get_attachment for bytes).

Fetch all messages in a Gmail thread (by gmThrId), oldest first.

List all labels/mailboxes for the account, including special-use flags.

Download one attachment from a message by index. Provide savePath to write it to disk (required for files >5MB); otherwise returns base64.

Send an email from the account via Gmail SMTP. A copy is filed in Sent automatically. This delivers real mail — confirm before running.

Compose a draft and save it to the Drafts mailbox (does not send).

Create a new Gmail label (nested labels use '/', e.g. 'Clients/Acme').

Add and/or remove Gmail labels on a message. System labels use a backslash prefix (\Inbox, \Starred, \Important); custom labels use their plain name. Removing \Inbox archives.

Mark a message as read (\Seen).

Mark a message as unread.

Star a message.

Remove the star from a message.

Archive a message (remove it from the Inbox).

Move a message to Trash (reversible for ~30 days).

Move a message to a label: applies the target label and removes it from the Inbox.

PERMANENTLY delete a message (moves to Trash then expunges). Irreversible. Requires confirm:true. Prefer trash_message for a reversible delete.

Mark every message matching a query as read in one pass — e.g. {query:'is:unread', mailbox:'[Gmail]/Spam'}. Reaches Spam/Trash via the mailbox param. Use dryRun:true to preview the count; confirm:true for batches over 100.

Add and/or remove labels on every message matching a query (Gmail only). Provide add and/or remove. dryRun:true previews; confirm:true runs batches over 100.

File every message matching a query under a target label (Gmail: adds the label and removes it from the Inbox; other providers: moves to the folder).

Move every message matching a query to Trash (reversible ~30 days). Requires a query or mailbox. dryRun:true previews; confirm:true runs batches over 100.

PERMANENTLY delete every message matching a query in an explicit mailbox. On Gmail this only works inside Trash or Spam (use empty_trash / empty_spam, or bulk_trash then empty_trash). Irreversible; requires confirm:true (dryRun:true to preview).

PERMANENTLY delete everything in the Spam/Junk mailbox (optionally narrowed by query). Irreversible; requires confirm:true. Use dryRun:true to see the count first.

PERMANENTLY delete everything in the Trash mailbox (optionally narrowed by query). Irreversible; requires confirm:true. Use dryRun:true to see the count first.

Add and verify a mail account, storing its App Password in the macOS Keychain (never in the registry or logs). provider: gmail (default) | icloud | fastmail | imap. For 'imap' pass imapHost + smtpHost (ports default to 993 / 465, or 587 with smtpStartTls). SECURITY: the App Password is an argument to this call, so it passes through the agent's context and the MCP client's logs. For the most private path, add accounts in the app's GUI instead — there the password goes straight to the local engine and the model never sees it.