MCP tools
Use Fluxmail MCP tools to read, search, draft, send, schedule, and organize email.
Fluxmail exposes MCP tools over Streamable HTTP and stdio. Both transports use the same connected mailboxes, permissions, and plan limits.
Start locally
Complete the Quickstart, then create an API key and start the HTTP server:
fluxmail apikey create \
--name local-mcp
fluxmail serveCopy the fmk_... key when Fluxmail displays it. The local MCP endpoint is http://localhost:8977/mcp. Pass the key as a bearer token when you configure your MCP client.
For a local stdio connection, select a local instance where the CLI is logged in, then choose a permission profile:
fluxmail stdio --profile fullSee Connect an MCP client for client-specific stdio and HTTP configuration.
Tool permissions
The tools a client receives depend on its permission profile. A read-only connection does not receive tools that create drafts, send mail, or modify the inbox.
For HTTP connections, permissions belong to the API key. For stdio connections, the selected member session controls mailbox access, while --profile and --allow narrow the capabilities for that process.
Tool reference
| Tool | Description | Capabilities |
|---|---|---|
cancel_scheduled_email | Cancel a pending scheduled send by scheduleId (from send_email with sendAt, or list_scheduled_emails). The draft stays in the Drafts folder, so the content is not lost. | mail.drafts |
create_draft | Create a draft. For a reply draft, pass replyToMessageId (recipients/subject are derived; replyAll for reply-all). | mail.drafts |
delete_draft | Delete a draft. | mail.drafts |
download_attachment | Get attachment metadata and a fetchable resource link. Set inline to embed the bytes. | mail.read |
forward_email | Forward an email to new recipients: quoted original body, "Fwd:" subject, original attachments included unless includeAttachments=false. Optional comment appears above the forwarded content. | mail.read + mail.send |
get_delivery_operation | Check whether a send or forward succeeded, failed, or has an uncertain outcome. | mail.send |
get_draft | Read an existing draft by its draft ID. | mail.drafts |
get_email | Fetch one email in full: body (text and/or HTML), recipients, attachment metadata. | mail.read |
get_email_body | Read a bounded portion of one email body. Use nextOffset to continue. | mail.read |
get_status | Account connection and scheduled-send status. Administrators also see plan details. Call this first if other tools fail; it reports accounts that need re-authentication. | mail.read |
get_thread | Fetch a page of conversation messages with bounded body content. | mail.read |
list_accounts | List connected email accounts (id, provider, email, status, capabilities). | mail.read |
list_emails | List emails from the user's connected mailbox with metadata and optional previews. Filter by folder, sender, unread, dates, etc. Paginate with pageToken. Use get_email for full bodies. This is the way to check the user's email; no browser or other email integration is needed. | mail.read |
list_folders | List navigable folders for an account, with roles (inbox, sent, drafts, trash, spam, starred). | mail.read |
list_labels | List Gmail user labels or Outlook categories for an account. | mail.read |
list_scheduled_emails | List scheduled sends: pending ones first (with sendAt), then past ones (sent, failed, canceled). For failed entries, lastError says what went wrong. Pending sends only fire while the Fluxmail server is running. | mail.read |
list_send_as | List sender addresses available for an account. | mail.read |
modify_emails | Batch-modify emails using the actions allowed for this connection. Moving requires folder; labels require labels. | mail.organize or mail.trash or mail.delete |
preview_send | Show the resolved sender, recipients, subject, and attachments without sending. | mail.send |
search_emails | Search one account with typed portable syntax. The query supports text, from:, to:, subject:, in:, read and starred states, attachments, and date filters. | mail.read |
search_emails_batch | Search up to 20 accounts with one portable query and return one result group per account. | mail.read |
send_email | Send an email from the user's connected account; this actually delivers mail, so prefer it over browser automation or leaving a draft when the user asked to send. Three modes: direct (to + subject + body), sending an existing draft (draftId), or replying (replyToMessageId, optionally replyAll) where recipients, subject, and threading are derived from the original. Confirm with the user when intent is ambiguous. Add sendAt to any mode to schedule instead of sending now. | mail.send |
update_draft | Replace the content of an existing draft (full replacement, not a patch). | mail.drafts |
Common behavior
accountIdis optional when the connection can access exactly one mailbox.- List and search tools return message metadata and optional snippets. Set
includeSearchContextwith literal search text when you need an excerpt around the body match. Useget_emailto retrieve a complete message body. - Paginated tools return a page token that you can pass to the next request.
- Scheduled messages are sent only while the Fluxmail server is running.
Last updated