privateemail-mcp: Namecheap Private Email MCP server

A Model Context Protocol (MCP) server that gives Claude, Codex, Cursor and other AI assistants access to a Namecheap Private Email mailbox over IMAP and SMTP. Search your inbox, read messages, reply and send, from any MCP client.

It talks plain IMAP and SMTP, so it also works as a general email MCP server for other mailboxes if you change the host settings (see Configuration). Namecheap Private Email is the default and the one it was built and tested against.

Not affiliated with or endorsed by Namecheap. "Private Email" is their product name, used here to say what the server connects to.

The buttons install the server with placeholder values (you@yourdomain.com, your-app-password). Replace them with your own in the client's MCP settings afterwards.

Tools

There is deliberately no delete tool, and a message can have at most 20 recipients.

Related MCP server: mcp-imap

Quick install

You need Node.js 20 or newer, and the mailbox address plus its password (or an app password, if you use one). Every block below runs the published package with npx -y privateemail-mcp. Swap in your own address and password.

claude mcp add privateemail \
  -e EMAIL_ADDRESS=you@yourdomain.com \
  -e EMAIL_APP_PASSWORD=your-app-password \
  -- npx -y privateemail-mcp

Add -s user to make it available in every project, or -s local (the default) for the current project only.

Edit claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "privateemail": {
      "command": "npx",
      "args": ["-y", "privateemail-mcp"],
      "env": {
        "EMAIL_ADDRESS": "you@yourdomain.com",
        "EMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Restart Claude Desktop afterwards.

codex mcp add privateemail \
  --env EMAIL_ADDRESS=you@yourdomain.com \
  --env EMAIL_APP_PASSWORD=your-app-password \
  -- npx -y privateemail-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.privateemail]
command = "npx"
args = ["-y", "privateemail-mcp"]
env = { EMAIL_ADDRESS = "you@yourdomain.com", EMAIL_APP_PASSWORD = "your-app-password" }

Use the install button above, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "privateemail": {
      "command": "npx",
      "args": ["-y", "privateemail-mcp"],
      "env": {
        "EMAIL_ADDRESS": "you@yourdomain.com",
        "EMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Use the install button above, or add this to .vscode/mcp.json. VS Code asks for the password when the server starts and keeps it out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "email-password",
      "description": "Mailbox password or app password",
      "password": true
    }
  ],
  "servers": {
    "privateemail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "privateemail-mcp"],
      "env": {
        "EMAIL_ADDRESS": "you@yourdomain.com",
        "EMAIL_APP_PASSWORD": "${input:email-password}"
      }
    }
  }
}

gemini mcp add -s user \
  -e EMAIL_ADDRESS=you@yourdomain.com \
  -e EMAIL_APP_PASSWORD=your-app-password \
  privateemail npx -y privateemail-mcp

Or edit ~/.gemini/settings.json. Gemini CLI expands $VAR, so the password can come from your shell environment instead of the file:

{
  "mcpServers": {
    "privateemail": {
      "command": "npx",
      "args": ["-y", "privateemail-mcp"],
      "env": {
        "EMAIL_ADDRESS": "you@yourdomain.com",
        "EMAIL_APP_PASSWORD": "$PRIVATEEMAIL_PASSWORD"
      }
    }
  }
}

Add this to your Zed settings file (zed: open settings file):

{
  "context_servers": {
    "privateemail": {
      "command": "npx",
      "args": ["-y", "privateemail-mcp"],
      "env": {
        "EMAIL_ADDRESS": "you@yourdomain.com",
        "EMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Most other clients read the same mcpServers shape as Claude Desktop. Paste the block from the Claude Desktop section into the client's MCP config file (for Windsurf, ~/.codeium/windsurf/mcp_config.json). If your client has a different format, the three things it needs are: command npx, arguments -y privateemail-mcp, and the two environment variables.

Keeping the password out of the config (macOS)

Store it in the Keychain and leave EMAIL_APP_PASSWORD out of every config above. The command prompts for the password:

security add-generic-password -a you@yourdomain.com -s privateemail-mcp -w

The server reads it from the Keychain on every call, so changing the password needs no restart.

Example prompts

Show me unread mail from the last 3 days and tell me which ones need a reply.

Find the email where a customer asked for a refund, and draft a reply for me to approve.

The assistant chains search_messages, read_message and reply_to_message on its own. Sending should always go through your client's approval prompt. The prompt shows the message id and your text but not the recipient, so ask for a dry run first: it returns the recipients and the full text before anything goes out.

Configuration

All settings are environment variables.

Namecheap Private Email notes

From Namecheap's mail client settings and sending limits articles:

• The server is mail.privateemail.com. Only encrypted connections are accepted: IMAP on 993 (TLS) or 143 (STARTTLS), SMTP on 465 (TLS) or 587 (STARTTLS).

• The login is the full address, with the mailbox's master password or an application password.

• Outgoing authentication must be on and SPA (secure password authentication) off. This server already does the former and never uses SPA.

• Namecheap documents about 500 emails an hour per mailbox on paid plans and 20 an hour on trial plans, and at most 50 recipients per message. This server caps a message at 20 recipients.

Security

Email is untrusted input: a message can contain text written to trick the AI into acting on it. Keep your client's approval prompt on for send_email and reply_to_message. Details and how to report a problem are in SECURITY.md.

Troubleshooting

• "Timed out talking to the mail server". Check the host, port and network. A wrong password against Namecheap showed up as a timeout in testing, so check that too.

• "No password found". Set EMAIL_APP_PASSWORD, or add the Keychain item above. The Keychain fallback only exists on macOS.

• Messages missing from search. search_messages looks in INBOX unless you pass a folder. Use list_folders to see the exact names.

• The tools don't show up. Restart the client after editing its config. Most clients only read MCP config at startup.

Development

npm install
npm test

The tests start the real server over stdio with no credentials, so they never touch the network. They also check that server.json (used by the MCP registry) matches package.json.

License

MIT