# smails [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/pexni/smails  
**GitHub Stars:** 39  
**npm Downloads (last month):** 441  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/smails

## Description
Disposable email for AI agents: create a throwaway inbox and read verification emails over MCP.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "smails": {
    "command": "npx",
    "args": ["-y","@smails/cli"]
  }
}
```

## Documentation

## What the smails MCP server does

The smails MCP server gives an AI agent access to a temporary mailbox without requiring a user account or password. It connects to the smails.dev service, which provides disposable email addresses for sign-ups, one-time codes, and confirmation messages.

An agent can create a mailbox, check its contents, retrieve a specific message, remove a message, and ask for the current address. Mailboxes are intended for temporary use and are removed after seven days without activity. The service supports multiple receiving domains, although the available domains are configured by the deployment.

## How it works

The MCP server runs through the `@smails/cli` npm package. An MCP client starts the CLI with the `mcp` command, and the CLI uses smails' API to perform mailbox operations. The service returns an address and an access token when a mailbox is created; later API requests use that token for authentication.

Messages are accepted through Cloudflare Email Routing and stored by a Cloudflare Durable Object assigned to the mailbox. Each mailbox uses SQLite storage inside its Durable Object. New-mail notifications can also be delivered through a WebSocket connection, allowing the underlying service to receive mail without repeatedly polling.

The smails MCP server is useful for agent workflows that need to complete an email verification step, inspect an incoming magic link, or isolate temporary registration mail from a personal inbox. It is not presented as a general-purpose email account or long-term mailbox.

## Setup and configuration

Add the server to an MCP client that supports stdio processes. The documented configuration starts `npx` with the `@smails/cli` package and its `mcp` subcommand:

```json
{
  "mcpServers": {
    "smails": {
      "command": "npx",
      "args": ["@smails/cli", "mcp"]
    }
  }
}
```

The README specifically shows this configuration for Claude Desktop and notes that it can be used with Cursor or another MCP client. For local development, set `SMAILS_API_URL` to the local worker address, such as `http://localhost:8787`, before running the CLI. The hosted service is used by default when no local development URL is supplied.

## Tools and capabilities

The MCP tool set contains five operations:

- `create_mailbox`: create a new disposable inbox.
- `list_messages`: retrieve messages in the mailbox.
- `read_message`: fetch a full parsed message by ID; an ID prefix is accepted by the CLI.
- `delete_message`: remove a message.
- `get_address`: return the mailbox address.

The same mailbox can also be accessed through the smails web interface, CLI, and REST API. The CLI provides equivalent commands for creating an inbox, listing and reading messages, displaying the current address, and replacing the current mailbox.

## Limitations and notes

Mailboxes expire after seven days of inactivity. Activity renews the cleanup timer, but the service is designed for temporary mail rather than durable storage. Access depends on the mailbox token, which combines the address with a secret and is used to authenticate requests.

The MCP package and the hosted worker have separate release processes. Publishing the CLI and MCP package is a manual release, while the worker and frontend can be deployed through Cloudflare Workers Builds. Deploying a private instance requires configuring a catch-all Cloudflare Email Routing rule and receiving domains through the worker's `DOMAINS` setting.

_Full upstream README: https://allmcps.com/mcp/smails/readme_