Labsco
manybrain logo

Mailinator MCP Server

★ 4

from manybrain

Free disposable email for AI—check any @mailinator.com inbox, retrieve messages in multiple formats, and extract verification codes for automated workflows.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#git

Mailinator-CLI (and MCP Server)

A Node.js CLI tool and MCP (Model Context Protocol) server to interact with the Mailinator disposable email service. List emails in any inbox and retrieve individual messages in various formats, either from the command line or through AI assistants like Claude Desktop.

Features

CLI Features

  • 📬 List emails in any Mailinator inbox with numbered, human-readable table format
  • 📧 Retrieve individual emails by message ID or listing number
  • 🔒 Support for both public and private domains
  • 🎨 Multiple output formats (text, HTML, headers, links, JSON, etc.)
  • ⚡ Fast inbox caching for quick email retrieval
  • 🔑 Flexible API token configuration (environment variable or config file)
  • 🌐 Wildcard inbox searches (with API token)

MCP Server Features

  • 🤖 MCP server mode for integration with AI assistants (Claude Desktop, etc.)
  • 🛠️ Tools: list_inbox and get_email for active email operations
  • 📚 Resources: Read-only access via mailinator:// URIs for passive context
  • 🔌 HTTP-based server with configurable host/port
  • 🔄 Same functionality as CLI but accessible via MCP protocol

Inbox Caching

The inbox command caches the list of emails to ~/.config/mailinator/inbox-cache.json. This allows you to:

  1. Quickly retrieve emails by their listing number (1, 2, 3, etc.)
  2. Avoid re-running the inbox command for each email retrieval
  3. Auto-detect domain for email retrieval in MCP mode

The cache persists across CLI invocations until you run the inbox command again.

Validation Rules

Inbox Names

  • Maximum 50 characters
  • Alphanumeric characters and dots (.)
  • Cannot start or end with a dot
  • Pattern: [a-zA-Z0-9](https://github.com/manybrain/mailinator-cli/blob/HEAD/[a-zA-Z0-9.]*[a-zA-Z0-9])?

Wildcards

  • Requires API token
  • Only allowed in private domains (not public)
  • Formats: * (all inboxes) or prefix* (inboxes starting with prefix)
  • Only one wildcard at the end

Domains

  • Special values: public, private
  • Custom domains: Valid domain name format

Error Handling

The CLI provides clear error messages for common issues:

  • Validation Error: Invalid input (inbox name, domain, format)
  • API Error: Authentication failures, network issues, API errors
  • Cache Error: No cached inbox (run inbox command first)
  • Config Error: Configuration file issues (non-fatal warnings)

Exit codes:

  • 0 - Success or config warning
  • 1 - Validation error
  • 2 - API error
  • 3 - Cache error

Examples

Common Workflows

Check emails for a test account:

Copy & paste — that's it
# List emails
mailinator-cli inbox testuser public

# Read the first email
mailinator-cli email 1

# View headers of second email
mailinator-cli email 2 headers

Use with private domain:

Copy & paste — that's it
# Configure API token
export MAILINATOR_API_KEY=your_token_here

# List private inbox
mailinator-cli inbox myinbox

# Read email with summary
mailinator-cli email 1 summary

# View SMTP delivery log
mailinator-cli email 1 smtplog

Extract links from an email:

Copy & paste — that's it
mailinator-cli inbox newsletter public
mailinator-cli email 1 links

Search multiple inboxes:

Copy & paste — that's it
# Requires API token
mailinator-cli inbox test* private

Use as MCP server with Claude Desktop:

Copy & paste — that's it
# Start the server
export MAILINATOR_API_KEY=your_token_here
mailinator-cli --start-mcp-server

# In Claude Desktop, ask:
# "What emails are in the joe inbox?"
# "Show me that first email in summary format"
# "Get the SMTP log for that message"

API Endpoints

This tool uses the Mailinator CLI API v3:

  • Inbox: GET https://api.mailinator.com/cli/v3/domains/{domain}/inboxes/{inbox_name}
  • Email: GET https://api.mailinator.com/cli/v3/domains/{domain}/messages/{message_id}?format={format}
  • SMTP Log: GET https://api.mailinator.com/cli/v3/domains/{domain}/messages/{message_id}/smtplog

Note: The smtplog format uses a separate endpoint path, not a format query parameter.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to the Mailinator API itself, visit: Mailinator Support

For CLI tool issues, please open an issue in the repository.

Related Links