mailsocket — Claude Code MCP server: what it does, how to install
Supplies disposable email inboxes to coding agents and halts execution until a verification code or magic link lands in the inbox.
claude mcp add --env MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> --env MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> --transport stdio mcp -- uvx mailsocket-mcpWhat mailsocket does
This integration provides agents with dedicated mailbox tools. An agent generates an address with create_inbox, then calls wait_for_otp or wait_for_link. The process pauses until matching mail arrives. The agent receives the extracted link or token without managing manual polling loops. The link is never followed.
Running the server requires Python 3.10 or newer when executing locally with uvx mailsocket-mcp. Supplying MAILSOCKET_API_KEY is mandatory: omitting it makes the process stop immediately with exit status 2. Alternatively, clients can point directly to the remote URL at https://mcp.mailsocket.app/mcp.
Remote calls cap the blocking duration at 55 seconds to prevent network proxies from dropping the connection. For sandbox validation, send_test_code injects sample authentication messages directly into an inbox. That tool is throttled to 5 messages per inbox and 20 per account each hour.
What it helps with
- receive one-time verification passcodes during automated signups
- extract authentication magic links from incoming messages
- validate email receiving logic with simulated test codes
- provision throwaway inboxes without configuring mail infrastructure
Example prompts for the agent
- Generate a new disposable address and wait for the verification passcode.
- Check for a magic login link sent to inbox
inbox_id. - Trigger a sample verification code to inbox
inbox_idand read it back.
How to install mailsocket
1Platform CLI
claude mcp add --env MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> --env MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> --transport stdio mcp -- uvx mailsocket-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>
2Platform CLI: remote server
claude mcp add --transport http mcp https://mcp.mailsocket.app/mcp1Platform CLI: remote server
codex mcp add mcp --url https://mcp.mailsocket.app/mcp2Platform CLI
codex mcp add mcp --env MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> --env MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> -- uvx mailsocket-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>
Config file
{
"mcpServers": {
"mcp": {
"url": "https://mcp.mailsocket.app/mcp"
}
}
}{
"mcpServers": {
"mcp": {
"command": "uvx",
"args": [
"mailsocket-mcp"
],
"env": {
"MAILSOCKET_API_KEY": "<MAILSOCKET_API_KEY>",
"MAILSOCKET_BASE_URL": "<MAILSOCKET_BASE_URL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>
Config file
{
"servers": {
"mcp": {
"type": "http",
"url": "https://mcp.mailsocket.app/mcp"
}
}
}{
"servers": {
"mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"mailsocket-mcp"
],
"env": {
"MAILSOCKET_API_KEY": "<MAILSOCKET_API_KEY>",
"MAILSOCKET_BASE_URL": "<MAILSOCKET_BASE_URL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>
1Platform CLI: remote server
gemini mcp add -t http mcp https://mcp.mailsocket.app/mcp2Platform CLI
gemini mcp add -e MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> -e MAILSOCKET_BASE_URL=<MAILSOCKET_BASE_URL> mcp uvx mailsocket-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mailsocket-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mailsocket
How to install mailsocket in Claude Code?
Run claude mcp add mailsocket-mcp -e MAILSOCKET_API_KEY=<MAILSOCKET_API_KEY> -- uvx mailsocket-mcp in your terminal. Replace the placeholder with your actual key.
What does mailsocket do?
It equips agents with tools to generate temporary inboxes and intercept authentication messages. Agents read verification codes and magic links directly without polling APIs manually.
What is the difference between local execution and the remote endpoint?
The hosted server limits waiting functions to 55 seconds to stay below proxy timeouts. The local stdio runner allows waiting intervals up to 120 seconds.
