# mailsocket

> mailsocket is an open-source MCP server for developer tools. MCP server giving AI agents test inboxes that wait for OTP codes and magic links. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, CLI, self-hosted
- **Website:** https://dash.mailsocket.app/docs/
- **Repository:** https://github.com/mailsocket/mailsocket-sdk/tree/HEAD/mcp
- **MCP Registry name:** app.mailsocket/mailsocket-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [agent tooling](https://ai-powered.com/categories/agent-tooling)
- **Listing updated:** 2026-11-18

## About

The server wraps the mailsocket Python SDK and exposes it as MCP tools, so a coding agent can create a throwaway inbox for each test run and block until a one-time code or magic link arrives, with no polling code of its own. Magic links are returned rather than followed. It is meant for testing apps you own or are authorized to test, not for creating accounts on services you don't control.

Besides create_inbox and the wait tools, it offers listing and filtering of inboxes and messages, fetching the newest message, deleting inboxes, and a send_test_code tool that drops a sample OTP email straight into an inbox so the wait loop can be checked without real mail. Waits are bounded: 120 seconds locally and 55 seconds on the hosted remote server. A `since` parameter lets a reused inbox return only the new code.

It runs locally over stdio via uvx or pip, or remotely over Streamable HTTP with a Bearer API key header. Note that the Mailsocket website and API were shut down on November 13, 2026, so API keys no longer work and inboxes no longer receive mail. The open-source SDKs remain on GitHub for reference.

## Features

- **Blocking OTP wait:** wait_for_otp holds until a one-time code arrives and returns it with confidence, subject, sender and timestamp.
- **Magic link extraction:** wait_for_link returns the extracted link without following it, plus message metadata.
- **Per-test inboxes:** create_inbox and delete_inbox manage disposable inboxes for each test run.
- **Sample code injection:** send_test_code places a sample OTP email in an inbox so the wait loop can be verified without real email.
- **Message browsing:** list_inboxes, list_messages and get_latest provide paginated and filtered access to mail.
- **Stdio and remote transports:** Run locally with uvx or pip, or connect to the hosted Streamable HTTP endpoint with a Bearer header.
- **Safe error handling:** SDK errors become clean MCP tool errors without stack traces, and the API key is never echoed.

## Good for

- Letting a coding agent complete signup flows that require an emailed OTP in end-to-end tests
- Verifying magic-link login in an app you own
- Testing password reset emails in CI-style agent workflows
- Checking an agent's wait loop with a synthetic OTP before using real email

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http mailsocket-mcp https://mcp.mailsocket.app/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://mcp.mailsocket.app/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mailsocket-mcp": {
      "url": "https://mcp.mailsocket.app/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mailsocket-mcp": {
      "type": "http",
      "url": "https://mcp.mailsocket.app/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mailsocket-mcp": {
      "serverUrl": "https://mcp.mailsocket.app/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mailsocket-mcp": {
      "type": "http",
      "url": "https://mcp.mailsocket.app/mcp"
    }
  }
}
```

## Tools

- `create_inbox`: Creates a fresh inbox and returns its id and address.
- `wait_for_otp`: Blocks until an OTP arrives and returns it with confidence and message metadata.
- `wait_for_link`: Blocks until a magic link arrives and returns the extracted link without following it.
- `list_inboxes`: Returns one page of inboxes owned by the key.
- `list_messages`: Returns one page of messages in an inbox, with optional filters.
- `get_latest`: Returns the newest message in an inbox without blocking.
- `send_test_code`: Puts a sample OTP email into an inbox for testing the wait loop.
- `delete_inbox`: Removes an inbox.

## FAQ

### Is Mailsocket still operating?

No. The website and API were closed on November 13, 2026; API keys no longer work and inboxes no longer receive mail. The SDKs remain on GitHub and npm.

### How do I run the server locally?

Run `uvx mailsocket-mcp` or install it with pip, and set MAILSOCKET_API_KEY in the environment. Python 3.10+ is required.

### Is there a hosted version?

Yes, at https://mcp.mailsocket.app/mcp over Streamable HTTP, authenticated with an Authorization Bearer header. Waits are capped at 55 seconds per call.

### How long can wait calls block?

The requested timeout is clamped to 120 seconds locally and 55 seconds on the remote server.

### Is mailsocket free?

Yes. mailsocket is open source, so you can use and self-host it for free.

### How do I add mailsocket to Claude Code?

Run this command in your terminal: claude mcp add --transport http mailsocket-mcp https://mcp.mailsocket.app/mcp

### What are the best alternatives to mailsocket?

The closest alternatives to mailsocket are Proxy Mail QA, MailFixture, BlinkInbox, GetCourier (moved) and Test Mailbox.

## Where this comes from

- Description: written from the project's README, the project's website and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Proxy Mail QA](https://ai-powered.com/mcp/proxy-mail-qa): Proxy Mail QA is a freemium MCP server for developer tools.
- [MailFixture](https://ai-powered.com/mcp/mailfixture): MailFixture is a freemium MCP server for communication.
- [BlinkInbox](https://ai-powered.com/mcp/blinkinbox): BlinkInbox is a freemium MCP server for developer tools.
- [GetCourier (moved)](https://ai-powered.com/mcp/getcourier-moved): GetCourier (moved) is a freemium MCP server for agent tooling.
- [Test Mailbox](https://ai-powered.com/mcp/test-mailbox): Test Mailbox is an MCP server for developer tools.
- [smails](https://ai-powered.com/mcp/smails): smails is a free MCP server for communication.
- [model.tools — Zero-Auth Agent Utilities](https://ai-powered.com/mcp/model-tools-zero-auth-agent-utilities): model.tools — Zero-Auth Agent Utilities is a free MCP server for developer tools.
- [MailBots](https://ai-powered.com/mcp/mailbots): MailBots is an MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/mailsocket
