Mailbird Next ships a built-in Model Context Protocol (MCP) server that lets AI assistants — like Claude, ChatGPT, OpenClaw, Cursor, and Wingman AI — read your mailbox, draft replies, and (with your explicit permission) act on your behalf. This guide walks you through enabling the server in Mailbird and connecting your favourite AI assistant to it in under five minutes.

🔌 What you'll get

• Read your inbox in plain language. "Check my inbox", "any reply from Mira yet?", "summarize this thread" — the assistant uses Mailbird's own data, not a separate sync.
• Draft replies that read like you. The assistant prepares the draft inside Mailbird; you review and send.
• Take action when you ask. Archive, snooze, move, star, mark as read, trash, even unsubscribe from newsletters — with your explicit go-ahead.
• Local-only and private. The server binds to 127.0.0.1, requires a bearer token, and never accepts connections from the internet.

📋 What you need

• Mailbird Next (any recent build).
• An MCP-capable AI client. This guide covers Claude Desktop, ChatGPT, and OpenClaw. Claude Desktop can connect through the local bridge configuration below; other clients need support for local HTTPS MCP endpoints or their own secure local-connector flow.

1️⃣ Enable the MCP server in Mailbird

1. Open Mailbird Next.
2. Click the Settings icon in the bottom-left corner.
3. Open the Wingman AI tab.
4. Toggle Enable MCP server on. The Status row updates to show Running on https://127.0.0.1:<port>/mcp.
5. Click Copy token next to Authentication token — you'll paste this into your AI client in a moment.

Tip: keep the Wingman AI tab open while you set up your AI client — you'll need both the endpoint URL and the token.

2️⃣ Connect your AI assistant

Mailbird's MCP server speaks the open MCP standard, so any client that supports MCP can use it. Pick the section that matches the client you use:

🤖 Claude Desktop

1. Open Claude Desktop.
2. Click Settings → Developer.
3. Click Edit Config — this opens claude_desktop_config.json in your default text editor.
4. Add (or merge) the mailbird entry into mcpServers. Replace YOUR-TOKEN-HERE with the token you copied from Mailbird, and adjust the port if Mailbird shows a different one:

   {
     "mcpServers": {
       "mailbird": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@latest",
           "https://127.0.0.1:52000/mcp",
           "--header",
           "Authorization: Bearer YOUR-TOKEN-HERE"
         ],
         "env": {
           "NODE_TLS_REJECT_UNAUTHORIZED": "0"
         }
       }
     }
   }

5. Save the file and restart Claude Desktop. The mailbird server should now appear under Local MCP servers with a green running badge.

The NODE_TLS_REJECT_UNAUTHORIZED setting is required because Mailbird uses a local self-signed HTTPS certificate. It applies only to the mcp-remote process Claude starts for this Mailbird connection.

Set tool permissions. In Claude, open Settings → Connectors → mailbird → Tool permissions. Choose how each tool should behave:

• Always allow — run without asking. Convenient for the read-only tools (list_conversations, get_message, etc.).
• Needs approval — Claude asks before each call. Sensible default for write actions while you're getting comfortable.
• Blocked — prevent Claude from ever calling that tool.

For a smooth first experience you can flip the group toggle to Always allow; you can always lock down individual tools later.

🧠 ChatGPT

ChatGPT does not currently support the same local Desktop configuration file that Claude Desktop uses. To connect ChatGPT to Mailbird's local MCP server, use OpenAI's Secure MCP Tunnel flow.

For step-by-step instructions, see Connect ChatGPT to Mailbird Next with Secure MCP Tunnel.

If you only need local desktop access without Developer Mode, use Claude Desktop with the configuration above or another local MCP client that supports HTTPS localhost endpoints and bearer-token headers.

🦅 OpenClaw

OpenClaw has a one-command setup via the Mailbird skill on ClawHub:

1. Install OpenClaw (cross-platform) — see openclaw.ai for instructions.
2. Install the Mailbird skill: openclaw skills install mailbirdagent/mailbird-mcp
3. When prompted, paste the endpoint URL and bearer token from Mailbird's Wingman AI tab.

The skill teaches OpenClaw the safety rules around sending and the common pitfalls, so you can move straight to asking it for things.

🛠 Any other MCP client

Cursor, Wingman AI, Continue, and other MCP clients can use the same configuration shape if they support local Streamable HTTP MCP: an HTTPS URL and an Authorization: Bearer <token> header. Use the values from Mailbird's Wingman AI tab and follow your client's "Add MCP server" flow.

5️⃣ Try it

Open your AI assistant and ask one of these:

• "Check my inbox and tell me what's new."
• "Draft a reply to Mira saying I'm running ten minutes late."
• "Summarise the thread I have open."
• "Find that invoice from Stripe in March."
• "Archive every newsletter from this week."
• "Unsubscribe from this sender."

Read tools (list, read, search, summarise) work immediately — no extra permission needed.

✏️ Letting your assistant write on your behalf

By default the MCP server is read-only. To let an assistant archive, trash, mark as read, snooze, or draft replies, flip Allow write actions on in the Wingman AI tab. You can turn it off at any time.

A few important guardrails are always on, regardless of the toggle:

• Sending always asks for confirmation. When the assistant prepares an outgoing email, it creates a draft and requires your explicit confirmation before sending. There is no "silent send" mode.
• You see a 5-second undo toast after every send, just like in normal Mailbird use.
• Permanent delete is restricted — only conversations already in Trash or Spam can be permanently deleted, mirroring Mailbird's UI.

📜 Audit log (optional)

If you want a record of every MCP request, enable Audit log of MCP requests in the Wingman AI tab. Mailbird appends the method name and parameters of each request to a local log file. Click Open log file to review it any time. Responses are not logged because they may contain private message content.

🔧 Troubleshooting

• "Connection refused" — Check that the Wingman AI tab still shows Running on …. If it shows Stopped, toggle the server back on, then click Restart.
• "Unauthorized" — The token may have changed. Click Copy token in Mailbird again, paste the fresh value into your client's configuration, and reconnect. Tokens regenerate when the server is disabled and re-enabled.
• Assistant refuses to send / archive / trash — Verify Allow write actions is on in the Wingman AI tab. Without it, the assistant only has read access.
• A message you just sent isn't in search results — The search index updates a few seconds after a message arrives or is sent. Wait 10–30 seconds and try again, or ask the assistant to list the Sent folder directly.
• Claude Desktop says "command not found: npx" — Install Node.js from nodejs.org. The mcp-remote bridge runs under Node.
• Claude reports DEPTH_ZERO_SELF_SIGNED_CERT — Make sure the env block from the sample JSON is present. Node otherwise rejects Mailbird's local self-signed HTTPS certificate.
• Claude reports an OAuth or 404 error — Make sure the --header argument is present and that you replaced YOUR-TOKEN-HERE with the token copied from Mailbird. Without the bearer header, mcp-remote may try an OAuth discovery flow that Mailbird's local server does not use.

🔒 Privacy & security

• The MCP server is off by default. Nothing happens until you enable it.
• It binds to loopback only (127.0.0.1). Other devices on your network — and the internet — can't reach it.
• Every request must include a bearer token that's generated locally and stored in your Mailbird settings. Token comparison is constant-time to resist token-guessing attacks.
• Write actions require an explicit one-time grant separate from read access. Send actions require an additional per-call confirmation.
• Mailbird never sends your mail content to any third party as part of running the MCP server. The assistant (Claude, ChatGPT, OpenClaw, etc.) is what reads the data — and only the data needed to answer your prompt.

📚 Tool reference

A complete list of the tools Mailbird's MCP server currently exposes. Read and utility tools work as soon as the server is running. Write tools require the Allow write actions toggle. send_message_now also requires confirm: true, and permanent delete is marked as destructive.

Read and utility tools

• get_ui_state — Get the user's current selected account, folder, and conversation summary. Use this first when the user says "the selected", "current", or "open" email.
• list_accounts — List configured email accounts, including sender name, email address, and unread conversation count.
• list_folders — List folders for an account, including folder id, name, identity such as Inbox/Sent/Trash, and parent folder id.
• list_conversations — List conversations in a folder, newest first, with unread, starred, important, timestamp, sender, and message-count metadata.
• get_conversation — Get one conversation and its message previews. Use get_message for the full body of a specific message.
• get_message — Get a full message body as markdown, with sender, recipients, subject, timestamps, and attachment metadata.
• search_conversations — Search conversations by free text or Mailbird syntax such as from:alice subject:invoice. Results include actual folder ids for follow-up actions.
• summarize_inbox — Quickly triage recent inbox conversations across all accounts or a specific account.
• list_attachments — List attachment metadata for a message, including id, filename, MIME type, size, content id, embedded flag, and download state.
• get_attachment_content — Fetch an attachment by messageId and attachmentId. Images return as viewable image content; other files return as base64 resources. Mailbird downloads on demand when needed and caps responses at 10 MB.
• get_send_status — Check whether a sent message has left Drafts. Useful after send_message_now.
• show_notification — Show an assistant card in Mailbird's bottom-right corner with optional clickable conversations or drafts. This does not mutate mail and is available without the write-action grant.

Draft, reply, and send tools

• create_draft — Create a new draft for an account with recipients, subject, body, and optional attachments. Attachments are URLs: a mailbird:// attachment URI from list_attachments or a local file:// path.
• update_draft — Update an existing draft's subject, body, or recipients. Passed recipient fields replace the current values; omitted fields are kept.
• discard_draft — Permanently delete a draft by message id. Irreversible.
• reply_to_conversation — Create a reply draft to the latest message in a conversation. The draft is saved but not sent.
• reply_all_to_conversation — Create a reply-all draft to the latest message in a conversation. The draft is saved but not sent.
• forward_conversation — Create a forward draft from the latest message in a conversation. Recipients can be added with update_draft.
• send_message_now — Send a reviewed draft by messageId, or build and send a new message in one call with accountId, recipients, body, and optional attachment URLs. Requires confirm: true; Mailbird's undo toast still applies.

Conversation action tools

• archive_conversation — Archive a conversation, moving it out of Inbox. The conversation may receive a new id in the archive folder.
• move_conversation — Move a conversation from one folder to another. The destination copy may receive a new conversation id.
• move_conversation_to_inbox — Move a conversation back into the Inbox.
• copy_conversation — Copy a conversation to another folder while leaving the original in place.
• trash_conversation — Move a conversation to Trash. Drafts or scheduled messages in the conversation may be discarded as a side effect.
• delete_conversation_permanently — Permanently delete a conversation that is already in Trash or Spam. This is irreversible and destructive.
• mark_conversation_as_read — Mark a conversation as read.
• mark_conversation_as_unread — Mark a conversation as unread.
• mark_all_as_read_in_folder — Mark every conversation in a folder as read.
• star_conversation — Star a conversation.
• unstar_conversation — Remove the star from a conversation.
• flag_conversation_important — Mark a conversation as important.
• unflag_conversation_important — Remove the important flag.
• snooze_conversation — Snooze a conversation until an ISO-8601 timestamp.

Spam, sender, and newsletter tools

• mark_conversation_as_spam — Move a conversation to Spam.
• unmark_conversation_as_spam — Restore a conversation from Spam to its original location.
• block_sender — Block the sender of a message. Future mail from that address is routed to Spam.
• unblock_sender — Remove a sender from the block list.
• unsubscribe_from_newsletter — Use a message's List-Unsubscribe header to unsubscribe when available. Personal mail usually does not have this header.

❓ Need More Help?

If you have any questions about Mailbird Next's MCP server, or you'd like a feature added, our support team is happy to help — contact us here and we'll get back to you quickly.