mailsocket
MCP server giving AI agents test inboxes that wait for OTP codes and magic links
- Pricing
- Open source
- Platforms
- API, CLI, self-hosted
- Runs
- Locally or Remotely
- Version
- 0.4.2
- Listing updated
- today
Similar MCP servers
About mailsocket
mailsocket is an open-source MCP server for developer tools. It can run locally on your machine or as a hosted remote server.
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.
Install
Run in a terminal
claude mcp add --transport http mailsocket-mcp https://mcp.mailsocket.app/mcpAdd to Settings → Connectors → Add custom connector
https://mcp.mailsocket.app/mcpAdd to ~/.cursor/mcp.json
{
"mcpServers": {
"mailsocket-mcp": {
"url": "https://mcp.mailsocket.app/mcp"
}
}
}Add to .vscode/mcp.json
{
"servers": {
"mailsocket-mcp": {
"type": "http",
"url": "https://mcp.mailsocket.app/mcp"
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"mailsocket-mcp": {
"serverUrl": "https://mcp.mailsocket.app/mcp"
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"mailsocket-mcp": {
"type": "http",
"url": "https://mcp.mailsocket.app/mcp"
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
MAILSOCKET_API_KEYmailsocket API key (ms_live_...). Create one in the dashboard or via POST /api/v1/agents/register.RequiredMAILSOCKET_BASE_URLOverride the API base URL. Defaults to https://dash.mailsocket.app/api/v1.
Tools this server provides (8)
Taken from the project documentation; the running server may differ.
- 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.
What it does
- 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
Pricing
Open source
Prices change. Check dash.mailsocket.app before you buy.
mailsocket 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.


