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 | Download an email attachment as an embedded MCP resource. | 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_email | Fetch one email in full: body (text and/or HTML), recipients, attachment metadata. | 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 full conversation thread with all message bodies. | 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 (metadata + snippet, no bodies). 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 |
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 |
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 |
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 snippets. Use
get_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