Connect Claude to your email with the Shipmail MCP server

Settings

Claude on the web, Claude Desktop and the mobile apps share one custom connector. Claude Code has its own setup, below. Use the local server only when you want Claude Desktop to run Shipmail on your computer.

Claude on the web, Desktop and mobile

1. Add the custom connector

   On claude.ai or in Claude Desktop, open Customize, then Connectors, choose Add custom connector and enter https://shipmail.to/api/mcp. Keep the sign-in on OAuth. The button below opens the dialog with the URL filled in.

   Add Shipmail to Claude

2. Sign in on Shipmail

   Claude sends you to the Shipmail sign-in page. Pick what Claude may do: Read and draft, Mail assistant, Full access, or Custom. Sign in with a mailbox address and its password to keep the connection to that one mailbox.

3. Turn it on in a chat

   Click the + button in the chat, open Connectors and switch Shipmail on. A connector you add on the web or in Desktop is also there the next time you open the Claude app on iOS or Android.

Free, Pro, Max and Ultra accounts add the connector themselves (Free allows one custom connector). On Team and Enterprise, an Owner adds it under Organization settings, then Connectors, and each member clicks Connect under Customize, then Connectors.

With an API key instead of OAuth

Anthropic is rolling out request headers for custom connectors to some organizations. If your Add custom connector dialog shows Request headers, choose No sign-in, add an authorization header and enter the value Bearer sm_live_..., with the word Bearer and a space. Claude sends the value exactly as typed. Otherwise use OAuth.

Create the mailbox and a scoped key

You need a Shipmail account with your domain added. Unlike a Gmail account made for a bot, a Shipmail mailbox is a paid business mailbox on your own domain, and giving it to an agent is what it is for. The address stays yours if you change agents later.

1. Create a mailbox for the agent

   Under Mailboxes, create an address like agent@yourdomain.com. You and your team can open it in Shipmail or any mail client and see every message Claude reads, drafts or sends.

2. Create an API key

   Open Developer, then API keys, and create a key. Pick the Draft only preset. It grants mailboxes:read, messages:read, messages:write, drafts:write, drafts:compose, threads:read and suppressions:read, and no messages:send.

3. Limit the key to that mailbox

   Choose specific resources and add only the agent's mailbox. The key then cannot read or write any other mailbox in your organization.

The key starts with sm_live_ and is shown once. The MCP server only lists the tools the key's scopes allow, so a Draft only key has no send tool at all. When the drafts are good, edit the key and switch to the Full agent preset, which adds messages:send and members:read. Scope details are on API authentication.

Claude Code

If Claude Code is signed in with your claude.ai account, the connector you added above already shows in /mcp. To add Shipmail to Claude Code on its own, with OAuth, run this, then type /mcp in Claude Code and sign in from the browser:

claude mcp add --transport http shipmail https://shipmail.to/api/mcp

Or connect with the scoped key you created:

claude mcp add --transport http --scope user shipmail https://shipmail.to/api/mcp \
  --header "Authorization: Bearer sm_live_..."

For a project server, commit .mcp.json and let each person keep their own key in SHIPMAIL_API_KEY. Claude Code expands the variable and asks before it uses a server from a project file.

{
  "mcpServers": {
    "shipmail": {
      "type": "http",
      "url": "https://shipmail.to/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SHIPMAIL_API_KEY}"
      }
    }
  }
}

Run the server locally in Claude Desktop

In Claude Desktop, open Settings, then Developer, and click Edit Config. That opens claude_desktop_config.json. Add Shipmail, save, then quit and reopen Claude Desktop. The server needs Node.js 20 or later.

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

First prompts to try

• "List the unread mail in agent@yourdomain.com from today and say which messages need me."
• "Draft a reply to the latest email from jane@customer.com saying the order ships Friday. Do not send it."
• "Find every thread with acme.com this month and summarize what is still open."

Open the mailbox in Shipmail. The draft sits in the same conversation, ready to edit and send.

Stay safe

• Start with Read and draft, or a Draft only key. Claude can read and write drafts, and you press send.
• Give Claude its own mailbox, like agent@yourdomain.com, and approve with that mailbox's password. Your own inbox stays out of reach.
• Read each tool approval request. Anthropic advises Always allow only for servers you trust. Under Customize, then Connectors, you can set a tool you never want to Blocked, such as shipmail_send_message.
• Treat every email as untrusted input. A message can carry text written to look like an instruction.
• Revoke the connection under Developer, then Connections, to cut access at once.

More on MCP permissions and security.

Troubleshooting

• You cannot add a second Shipmail connector: Claude allows one connector per server URL. Use the one you have, or remove it and add it again. Claude cannot edit a connector's sign-in settings, so a change always means remove and add.
• A tool is missing: the connection or key does not allow it. Widen the permissions in Shipmail, then disconnect and reconnect so Claude refreshes its tool list.
• Claude Code does not list the claude.ai connector: run /status. Connectors load only when Claude Code is signed in with a claude.ai subscription, not with an API key.
• The local server does not start: run npx -y shipmail-mcp in a terminal to see the error, check the JSON for a stray comma, and read mcp-server-shipmail.log in the Claude Desktop logs folder.

Next steps

• Every Shipmail MCP tool
• The Shipmail MCP server, with every other client.
• Connect ChatGPT or Cursor to the same mailbox.
• Email for AI agents, the overview of every way to connect.

Frequently asked questions