How to connect nicemails to Cursor

Q: nicemails doesn’t appear, or shows an error, in Cursor.

Check that mcp.json is valid JSON and that url is exactly https://nicemails.net/mcp. Open the Output panel (Cmd+Shift+U), choose MCP Logs and look for connection errors. Restart Cursor after you edit the file.

To give Cursor an email inbox, add nicemails to your mcp.json file with the nicemails MCP server address as its url. Cursor signs in with OAuth: you approve access on the nicemails page in your browser, and Cursor’s agent can then search and read your mailboxes, organize messages and send mail you approve.

What do you need before you start?

A nicemails account with a mailbox for Cursor to use. Sign-up is free and uses a code sent to your email instead of a password.
The Cursor desktop app. Per Cursor’s docs, Cursor supports Streamable HTTP servers and OAuth sign-in with PKCE, and registers itself as a client automatically, so you do not need a client ID.

How do I add nicemails to Cursor?

Open ~/.cursor/mcp.json to use nicemails in every project, or .cursor/mcp.json in a project folder to use it there only. Create the file if it does not exist, and add nicemails under mcpServers:
```
{
  "mcpServers": {
    "nicemails": {
      "url": "https://nicemails.net/mcp"
    }
  }
}
```
Save the file. If nicemails does not appear, restart Cursor.
Open Customize in the sidebar and check that nicemails is enabled.
Cursor reads the sign-in details from the nicemails server and starts OAuth. Your browser opens nicemails: sign in with the code sent to your email.
On the approval page, choose the permissions and whether Cursor may use every mailbox or only one, then select Allow.
In the Agent chat, ask “list my nicemails mailboxes”. Cursor uses the MCP tools listed under Available Tools when they are relevant.

The desktop app finishes sign-in at http://localhost:8787/callback, and nicemails accepts it, so there is nothing to allow-list. Cloud Agents keep their own MCP sign-ins on Cursor’s servers, so sign in again there if you use them.

How do I use an API key instead?

An API key suits a machine without a browser, or a project where you want one fixed, narrow credential. Create it first:

In nicemails, open Settings → API keys and select Create API key.
Choose AI agent (MCP) as the key purpose.
Pick the permissions and, if you like, limit the key to one mailbox.
Copy the key. It is shown only once.

Cursor expands ${env:NAME} in url and headers, so the key can stay out of the file. Set NICEMAILS_API_KEY in the environment Cursor starts from, then use:

{
  "mcpServers": {
    "nicemails": {
      "url": "https://nicemails.net/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NICEMAILS_API_KEY}"
      }
    }
  }
}

Do not commit a project .cursor/mcp.json that contains a key in plain text.

What can Cursor do with your mailboxes?

Cursor’s agent gets the nicemails tools your permissions allow. There are 8:

list_mailboxes lists the mailboxes the connection can use.
list_messages lists one folder of a mailbox, newest first.
search searches every folder of the selected mailboxes, including Spam.
get_message reads one message without marking it as read.
create_mailbox creates a new mailbox (Manage permission, account-wide connection).
move moves a message to another folder; flag marks it read, unread, starred or answered.
send_message sends from one of your mailboxes (Send permission; new recipients need your approval).

In a coding session that looks like: “Open the newest email in the qa mailbox from our staging app and paste the magic link into the end-to-end test,” or “Search for the invoice email template we sent yesterday and compare its subject with the one in the code.”

Who approves what Cursor does?

Per Cursor’s docs, Cursor asks for approval before it uses an MCP tool by default, following the same run modes as terminal commands. Under Auto-review, allow-listed tools run without a prompt.
Permissions: the connection gets only what you choose: Read (list, search and read mail), Manage (create mailboxes, move messages, set flags) and Send. A connection can also be limited to one mailbox.
Send approval: if a recipient is not someone you emailed from the web app, or trusted at an earlier approval, within the last 30 days, nothing is sent until you approve that message on a nicemails confirmation page while signed in. An unapproved request expires after 15 minutes.
Untrusted content: tool results mark email content as untrusted, and nothing inside an email can approve a send.
An off switch: disable nicemails under Customize, or disconnect Cursor in nicemails under Settings → API keys → Connected apps. Access ends immediately.

Troubleshooting

nicemails doesn’t appear, or shows an error, in Cursor.

Check that mcp.json is valid JSON and that url is exactly https://nicemails.net/mcp. Open the Output panel (Cmd+Shift+U), choose MCP Logs and look for connection errors. Restart Cursor after you edit the file.

Sign-in finished, but a tool fails.

The connection may not have that permission, or it is limited to another mailbox. Disconnect Cursor under Settings → API keys → Connected apps, then sign in again from Cursor and choose the permissions you need.

Does the connection work in Cursor’s Cloud Agents?

Cloud Agents keep their own MCP sign-ins, separate from the ones on your machine, so sign in to nicemails again from there.

Related guides

Start for free