How to connect nicemails to Claude Code

Q: /mcp shows nicemails as failed or needing sign-in.

Select nicemails in /mcp and sign in again. If that does not help, choose Clear authentication in the same menu and sign in once more. Run claude mcp get nicemails to check that the address is https://nicemails.net/mcp.

Q: How do I remove nicemails from Claude Code?

Run claude mcp remove nicemails. To end access on the nicemails side as well, disconnect the app under Settings → API keys → Connected apps, or revoke the key.

To give Claude Code an email inbox, add the nicemails MCP server with claude mcp add and the HTTP transport, then run /mcp in Claude Code and sign in to nicemails in your browser. After you approve the permissions, Claude Code can search and read your mailboxes, organize messages and send email you approve.

What do you need before you start?

A nicemails account with a mailbox for the work, such as qa-signups. Sign-up is free and uses a code sent to your email instead of a password.
Claude Code. Per the Claude Code docs, remote servers use the HTTP transport and the older SSE transport is deprecated. nicemails speaks Streamable HTTP, so no extra flags are needed.

How do I add nicemails to Claude Code?

In a terminal, add nicemails as a remote HTTP server. Without a scope flag, Claude Code keeps it for you in the current project only (local scope):
```
claude mcp add --transport http nicemails https://nicemails.net/mcp
```
Start Claude Code in that project and run /mcp. Select nicemails and sign in; your browser opens the nicemails sign-in page.
Sign in with the code sent to your email. On the approval page, choose the permissions and whether Claude Code may use every mailbox or only one, then select Allow.
Back in Claude Code, /mcp lists nicemails as connected. Ask “list my nicemails mailboxes” to try it.

The scope decides where the server is available. Local scope, the default, is just you in this project. Add --scope user to use nicemails in all your projects. --scope project writes it to .mcp.json in the project root, so teammates who check out the project get it too:

{
  "mcpServers": {
    "nicemails": {
      "type": "http",
      "url": "https://nicemails.net/mcp"
    }
  }
}

The file holds only the address. Each teammate signs in to their own nicemails account from /mcp.

Already added nicemails as a connector in Claude? When you sign in to Claude Code with your Claude account, that connector appears in /mcp automatically. If you also add the same address with claude mcp add, Claude Code’s own entry takes precedence and the connector is listed as hidden.

How do I use an API key instead?

Use a key for sessions without a browser, such as a CI job or a remote machine. 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.

Then add the server with the key as a header:

claude mcp add --transport http nicemails https://nicemails.net/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

In a shared .mcp.json, never write the key itself. Claude Code expands environment variables in headers, so each person sets NICEMAILS_API_KEY on their own machine:

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

What can Claude Code do with your mailboxes?

Claude Code gets the nicemails tools your permissions allow. There are 8, and each appears as mcp__nicemails__<tool>:

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

This is handy when you test sign-up flows. Ask: “Create a mailbox called signup-test-42, register it in the staging app, then find the verification email and open the link,” or “Search the qa mailbox for the password reset email we just triggered and check that the link points to staging.”

Who approves what Claude Code does?

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.
Claude Code’s own permissions still apply. nicemails marks list_mailboxes, list_messages, search and get_message as read-only and the other tools as changing data, so you can allow reading without a prompt and keep asking before mcp__nicemails__send_message.
Untrusted content: tool results mark email content as untrusted, and nothing inside an email can approve a send.
An off switch: disconnect Claude Code under Settings → API keys → Connected apps, or revoke its key. Access ends immediately.

Troubleshooting

/mcp shows nicemails as failed or needing sign-in.

Select nicemails in /mcp and sign in again. If that does not help, choose Clear authentication in the same menu and sign in once more. Run claude mcp get nicemails to check that the address is https://nicemails.net/mcp.

Claude Code doesn’t list the nicemails connector I added in Claude.

Connectors from Claude load only when Claude Code is signed in with a Claude subscription. Per the Claude Code docs, they are not loaded while ANTHROPIC_API_KEY or another API credential is active. Run /status to check, or add nicemails with claude mcp add.

How do I remove nicemails from Claude Code?

Run claude mcp remove nicemails. To end access on the nicemails side as well, disconnect the app under Settings → API keys → Connected apps, or revoke the key.

Related guides

Start for free