Connect Cursor to your email with the Shipmail MCP server

Settings

The global file puts Shipmail in every project. The project file keeps it to one repository.

Connect with OAuth

Click the button, or paste the link into a browser. Cursor asks you to confirm the install.

Or add the server to mcp.json by hand:

{
  "mcpServers": {
    "shipmail": {
      "url": "https://shipmail.to/api/mcp"
    }
  }
}

Cursor finds Shipmail's OAuth support from the URL and registers itself, so there is nothing else to fill in. When it signs in, you land on the Shipmail sign-in page. Pick what Cursor 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.

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 Cursor 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.

Connect with an API key

Send the key as a bearer header. Cursor fills in ${env:SHIPMAIL_API_KEY} from your environment, so the key stays out of the file:

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

Run the server locally instead

Cursor can start the stdio server on your machine. It needs Node.js 20 or later.

{
  "mcpServers": {
    "shipmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "${env:SHIPMAIL_API_KEY}"
      }
    }
  }
}

Open Customize in the sidebar to check that Shipmail is on and to see its tools.

First prompts to try

• "Summarize the unread mail in agent@yourdomain.com from today."
• "Find the bug report from jane@customer.com, fix it in this repository, then draft her a reply saying the fix ships Friday. Do not send it."
• "List the threads in support@yourdomain.com that mention the login page this week."

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. Cursor can read and write drafts, and you press send.
• Give Cursor its own mailbox, like agent@yourdomain.com, and limit the key to it. Your own inbox stays out of reach.
• Read each tool approval. Cursor asks before it runs an MCP tool by default, and the arrow next to the tool name shows the arguments. Keep the send tools off any allowlist.
• Treat every email as untrusted input. A message can carry text written to look like an instruction, and Cursor can edit code and run commands. Do not ask it to act on mail from people you do not know.
• Revoke an OAuth connection under Developer, then Connections, or a key under Developer, then API keys. Cursor loses access at once.

More on MCP permissions and security.

Troubleshooting

• The server does not connect: open the Output panel (Cmd+Shift+U), pick MCP Logs, and read the error.
• The key is refused: check that SHIPMAIL_API_KEY is set in the environment Cursor starts from, and that the header reads Bearer plus a space before the key.
• A tool is missing: the key or connection does not allow it. Edit the key under Developer, then API keys, or the connection under Developer, then Connections. Then switch the server off and on in Customize.
• The local server does not start: run npx -y shipmail-mcp in a terminal to see the error, and check your Node.js version.

Next steps

• Every Shipmail MCP tool
• Connect Claude, ChatGPT or Codex to the same mailbox.
• Receive email in an AI agent when you build your own agent with webhooks.
• Email for AI agents, the overview of every way to connect.

Frequently asked questions