Mailbird MCP

Mailbird MCP

You have access to a local Mailbird MCP server that exposes the user's real email accounts, folders, conversations, drafts, and attachments. It's running inside the user's Mailbird desktop app on 127.0.0.1 only — there is no remote variant.

The single most important rule: for ANY task that involves email, inbox, messages, drafts, contacts, attachments, folders, or sending — even when the user phrases it casually ("check my inbox", "any reply from X yet?", "draft a reply to that invoice", "find that thread from Mira") — reach for these tools first. Do not grep the local filesystem, do not read code, do not guess. The server is the source of truth.

Setup

The user enables the MCP server inside Mailbird at: Settings → Wingman AI → Enable MCP server.

That tab also exposes:

• The bearer token (Copy button).
• The endpoint URL (http://127.0.0.1:<port>/mcp, port shown next to status).
• The "Allow write actions" toggle — required before any write tool will work.

If the connection fails, ask the user to verify the toggle is on and that they've copied the current token. Tokens regenerate when the server is disabled and re-enabled.

Configuration (environment variables)

Both are optional; defaults work for a single-user local install.

Security model

This skill grants the agent access to the user's full mailbox: message bodies, attachments, contacts, and the ability to send mail (when the write-action gate is on). Treat the URL and token accordingly:

• The Mailbird MCP server only binds to loopback (127.0.0.1). Don't proxy, port-forward, or tunnel it to a public address. Don't paste the URL or token into any remote / cloud-hosted agent that doesn't run on the same machine as Mailbird.
• The token is a credential equivalent to mailbox login. Don't echo it into chat transcripts, commit it, share it in screenshots, or include it in bug reports. Tokens regenerate when the server is disabled and re-enabled — rotate immediately if it leaks.
• Write actions (archive, trash, send, etc.) require the user to flip Allow write actions in the Wingman AI tab. Sending additionally requires per-call confirm: true. The skill should always show drafts to the user before sending.
• Mailbird's optional Audit log of MCP requests records every call (method + params, never responses) to a local file the user can inspect. Recommend they enable it for visibility.

Start-of-session checklist

Run these the first time you touch the server in a session, before any non-trivial action:

1. Read mailbird://help via resources/read. It's the canonical user guide — covers the ID model, write-tool gating, send pipeline, search index lag, archive→restore, attachment handling, inline images. Skim it once and remember the key recipes.
2. list_accounts to learn the configured account ids.
3. For folder-scoped work, list_folders(accountId) and pick by the identity field — Inbox, Sent, Drafts, Trash, Spam, Archived, AllMail, Generic (user-created). Folder ids are NOT stable across accounts. list_accounts does not return the inbox folder id — always discover via list_folders.

Read tools (always available)

• list_accounts — accounts with id, sender name, email, unread count.
• list_folders(accountId) — folders for one account.
• list_conversations(folderId, limit?, unreadOnly?, starredOnly?, importantOnly?) — recent conversations in a folder.
• get_conversation(conversationId, folderId) — message list + metadata for one thread.
• get_message(messageId) — full message body, with cid: images rewritten to mailbird://messages/{messageId}/attachments/{attachmentId} resource URIs.
• get_unread_counts(accountId? | folderId?) — quick triage signal.
• search_conversations(query, accountId?, folderId?) — Mailbird search syntax (from:foo subject:bar). Results carry actualFolders[]; use those ids to act on hits, not the virtual folderId: -2.
• list_attachments(messageId) / get_attachment_status(...) / get_attachment_content(...).
• get_send_status(messageId) — sent / draft_pending_send / scheduled / trashed.

Write tools (gated by "Allow write actions")

• archive_conversation, trash_conversation, move_conversation, move_conversation_to_inbox.
• mark_conversation_as_read / unread, flag_conversation_important, star_conversation / unstar_conversation, mark_conversation_as_spam / unmark_conversation_as_spam, snooze_conversation(wakeAtUtc).
• create_draft(accountId, to, cc?, bcc?, subject, body, attachments?) — saves a draft, returns messageId. Does NOT send.
• update_draft(messageId, ...) — replace any field on an existing draft.
• reply_to_conversation, reply_all_to_conversation, forward_conversation — create a draft with the standard quoted scaffold and return messageId. Do NOT send. Body is up to you to finalise.
• send_message_now(messageId | accountId+to+...; confirm: true) — actually sends. Always show the draft to the user and get explicit approval first. Returns status: "queued" plus a deliveryState field signalling IMAP/SMTP health.
• unsubscribe_from_newsletter(messageId) — uses the List-Unsubscribe header. Returns structured "not_applicable" / "already_unsubscribed" when relevant.
• delete_conversation_permanently — only applies to conversations currently in Trash or Spam. From elsewhere, trash first then re-discover the new id and call this on the trash copy.

If a write tool returns an error pointing at the "Allow write actions" toggle, surface it to the user verbatim — do not retry.

Pitfalls (these bite less-careful agents)

1. Conversation IDs are per-folder. After trash_conversation, archive_conversation, or move_conversation, the conversation has a NEW id in its destination folder. Re-discover via list_conversations(folderId=<destination>) before chaining further actions. Message ids, on the other hand, are stable across folders.
2. Search index lag (~10–30s). A message you just sent or received may not be in search_conversations results yet. For very recent items, prefer list_conversations(folderId=<sent_folder>) over searching.
3. Send pipeline. send_message_now returns immediately with status: "queued". The message stays briefly visible in Drafts before moving to Sent — that's normal. Use get_send_status to confirm.
4. Archive destination depends on the provider. Gmail and IMAP-with-labels accounts archive into the AllMail folder; everything else uses Archived. Exactly one will exist per account. The full restore recipe (list_folders → list_conversations → move_conversation_to_inbox) lives in mailbird://help.
5. Inline (cid:) images in get_message results are rewritten to mailbird://messages/.../attachments/... URIs. Resolve via resources/read. The response also carries an inlineAttachments map.

Reply pattern

Standard chain for an agent-authored reply:

1. reply_to_conversation(conversationId, folderId)        → messageId
2. update_draft(messageId, body: "<your prose>")           # quoted scaffold preserved
3. <show draft to user, get approval>
4. send_message_now(messageId, confirm: true)              → status: queued
5. (optional, ~5s later) get_send_status(messageId)        → status: sent

For a brand-new message (no thread), use create_draft with to/subject/body/attachments directly, then steps 3–5.

When to escalate to the user

• Any write before "Allow write actions" is enabled.
• Any send — always show the draft and get approval.
• Permanent delete from anywhere other than Trash/Spam.
• Search returns nothing for content the user expects to exist (could be index lag, suggest the user wait and retry).

When uncertain about provider-specific behaviour or an edge case, read mailbird://help again — it's the authoritative source.