mcp-email

# @voidly/mcp-email

Email for AI agents. Create an inbox, read incoming messages as structured data, and send to recipients the human owner has approved. No phone number or CAPTCHA.

Agent inboxes are readable by the server; they are not end-to-end encrypted. [Human mail](https://voidly.ai/mail) is a separate product.

## Install

Requires Node.js 20 or newer.

```bash
npx -y @voidly/mcp-email@1.2.1
```

### Add to Cursor

Copy this install URI into your browser address bar. Cursor asks you to review the local command before adding it:

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=voidmail&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2b2lkbHkvbWNwLWVtYWlsQDEuMi4xIl19
```

For manual project setup, copy the JSON below into `.cursor/mcp.json` (or `~/.cursor/mcp.json` for all projects).

### Install in VS Code

Copy this install URI into your browser address bar. VS Code asks you to review the local command before adding it:

```text
vscode:mcp/install?%7B%22name%22%3A%22voidmail%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40voidly%2Fmcp-email%401.2.1%22%5D%7D
```

For manual workspace setup, copy the JSON below into `.mcp.json` at the workspace root. GitHub renders custom app URIs as plain text, so use the copyable snippets above.

```json
{
  "mcpServers": {
    "voidmail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@voidly/mcp-email@1.2.1"
      ]
    }
  }
}
```

These instructions run the **local stdio** package at 1.2.1. They do not create an inbox. The repository's root [`.mcp.json`](./.mcp.json) keeps that local command as `voidmail` and also offers the hosted connector as `voidmail-hosted` at `https://api.voidly.ai/mcp/mail`. It contains no credentials. The hosted connector has its own tool set; use `voidmail_setup` to check mailbox configuration before authenticated inbox actions.

**Before creating an inbox in a coding agent:** `voidmail_create_account` saves an owner key on the local machine. Keep that key outside the agent's shell and file access before handing the inbox to the agent. A 0600 file owned by the same OS user is not enough separation. The server can read message contents; provider acceptance of a send is not delivery.

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "voidmail": {
      "command": "npx",
      "args": ["-y", "@voidly/mcp-email@1.2.1"]
    }
  }
}
```

This first-time config has no inbox key. After `voidmail_create_account` returns an address and saves the keys, add `"env": {"VOIDMAIL_ADDRESS": "<returned-address>"}` to this server config and restart the host. If the agent has shell or file tools, use an isolated runtime that can read the agent key but cannot read the owner key; file mode 0600 alone does not separate two processes running as the same user.

## Quick Start

After installing the MCP server, use this prompt:

> Create one Voidmail inbox and show me its address and where the keys were saved. Draft emails first and wait for my approval before sending.

The draft approval in this prompt is a host workflow request. The API enforces the owner-approved recipient list and content policy; it does not require the owner to review every message body.

For a first receive and send check:

1. In a trusted owner-controlled host, call `voidmail_create_account` once. Keep the returned owner-key path outside any agent shell or file access before handing the inbox to an agent. If creation is uncertain, inspect the original setup before making another inbox.
2. Send one test message from a separate trusted mailbox to the new address. Call `voidmail_list_inbox`, then `voidmail_read_email` with the returned message ID. Reading marks that message as read.
3. In an owner-only terminal, run `npx -y @voidly/mcp-email@1.2.1 owner add you@example.com` (use your actual target address). Set `VOIDMAIL_OWNER_KEY_FILE` if you moved the owner key. The owner command reads it locally; never paste it into the model conversation. The agent can check `voidmail_policy` and `voidmail_sending_limits` afterward.
4. Review one recipient, subject and body. Save a unique 16-128 character operation ID (letters, digits, `_` or `-`) with that message in trusted host state, then call `voidmail_send_once`. If the response is uncertain, look up that same ID with `voidmail_send_status`; do not invent a replacement ID. A provider `accepted` result does not prove delivery.

## Permissions: two keys, one owner

Every inbox has two credentials, and this package keeps them apart.

| Key | File (0600, directory 0700) | Who uses it | What it can do |
|-----|------------------------------|-------------|----------------|
| Agent key `vm_…` | `~/.voidly/mcp-email/<address>/agent-key` | the MCP server, for the model's tools | read, send to approved recipients, request a recipient, remove a recipient, tighten policy |
| Owner key `vmo_…` | `~/.voidly/mcp-email/<address>/owner-key` | you, through `voidly-mcp-email owner` | approve or deny requests, add or remove recipients, lock or unlock, rotate either key |

- `voidmail_create_account` writes both files and returns only their paths. **This server never puts either key in a tool result.** Every message it emits is scrubbed of Voidmail key shapes (`vm_…`, `vmo_…`), including ones that arrive inside email. Other secrets that arrive in email, such as a cloud or GitHub token, are passed to the model unchanged.
- The MCP server never reads the owner-key file and never calls the owner API routes (`/v1/agent-mail/owner/*`). No tool uses the owner key.
- **Mode 0600 keeps other OS users out, not your agent.** Anything that runs as your user can read the owner-key file, including an agent with shell or file tools (a coding agent, a filesystem MCP server). Such an agent could read the owner key and approve its own recipients. If your agent has shell or file access on this machine, move the owner-key file somewhere it cannot read, or off the machine, and point `VOIDMAIL_OWNER_KEY_FILE` at it when you run owner commands.
- Inboxes created with this package start with an **owner-approved recipient list**, enforced by the Voidly API, not by model instructions. (A REST create that does not opt in still makes the old kind of inbox: no owner key, any recipient, credential warnings only. A create opts in with `recipient_policy: "allowlist"`, `owner_key: true` or `content_policy: "enforce"`; only then does the response carry an `owner_key`. This package always sends `recipient_policy: "allowlist"`.) Sending to anyone else returns `RECIPIENT_NOT_AUTHORIZED` with `send_attempted: false`. The API records a pending request, and the tool result says exactly what the owner must run.
- A message that looks like it carries a credential (private keys, cloud, GitHub, Slack, Stripe, AI-provider or Voidmail keys) is refused with `CONTENT_CONTAINS_CREDENTIAL` on inboxes with credential blocking on, which is the default for inboxes that have an owner key (every inbox this package creates). The tool result lists the kinds found, never the matched text. The check matches known key formats. It does not catch passwords, unfamiliar token formats or data that is sensitive for other reasons.
- **Outgoing mail is checked for credentials.** Before a message is sent, the API scans its recipient, subject, body and reply-to in memory for known credential formats. The scan keeps no copy of what it matched: it records only a daily count for each kind it found. On an inbox with credential blocking on (the default for inboxes with an owner key), a match stops the send. On other inboxes the message is still sent, and the response names the kinds found in an `X-Voidmail-Content-Warning` header. The owner can turn the check off at https://voidly.ai/agent-mail/owner (or with `POST /v1/agent-mail/owner/policy` and `content_policy: "off"`). The one exception is an owner key made by bootstrap, described below: it cannot switch the check off.
- The agent key can only restrict: it can remove a recipient or turn blocking on. Anything that widens what the agent can do needs the owner key.
- Approving a recipient takes the owner key, and nothing in an email can supply it through this server. Treat incoming mail as untrusted content.

### Owner commands

```bash
npx -y @voidly/mcp-email@1.2.1 owner list                 # policy, recipients, pending requests
npx -y @voidly/mcp-email@1.2.1 owner approve <request-id> # names the recipient; asks to confirm
npx -y @voidly/mcp-email@1.2.1 owner deny <request-id>
npx -y @voidly/mcp-email@1.2.1 owner add friend@example.com
npx -y @voidly/mcp-email@1.2.1 owner remove friend@example.com
npx -y @voidly/mcp-email@1.2.1 owner lock                 # allowlist + credential blocking
npx -y @voidly/mcp-email@1.2.1 owner unlock               # any recipient; asks to confirm
npx -y @voidly/mcp-email@1.2.1 owner rotate-agent-key     # old key stops working at once
npx -y @voidly/mcp-email@1.2.1 owner rotate-owner-key     # replaces the owner-key file it read
```

Add `--address <name@voidmail.ai>` when more than one inbox is saved, and `--yes` to confirm without a prompt. `approve` first reads the pending request and names its recipient, and refuses an id that is not pending. Rotated keys are written to their files and never printed. `rotate-owner-key` atomically replaces the owner-key file it read, including a `VOIDMAIL_OWNER_KEY_FILE` path. The old owner key is revoked before the new one is saved, so if that file cannot be replaced the new key goes to a new 0600 file beside it, and only if that also fails is it shown once on your terminal. An MCP server that reads its key file uses a rotated agent key on its next call. The same actions are available in the browser at https://voidly.ai/agent-mail/owner, where the owner key is kept in memory only.

**Inboxes without an owner key** (created before the owner-key API update