📧 TempMail OTP MCP - Apify Actor

Automate account registrations seamlessly. This Actor provides a high-performance temporary email service and automatic OTP extraction via the Model Context Protocol (MCP).

🚀 Overview

AI Agents struggle with checking emails during sign-up workflows. This MCP server simplifies the process into a few direct tool calls.

• On-Demand & Cost-Efficient: Connect only when you need an OTP. Each wait_for_otp call returns within ~45 s (under the typical 60 s MCP request timeout) — if no mail arrived yet it returns status: "pending", and the agent simply calls again. An idle connection auto-shuts down (default 5 min) so it never keeps burning compute in the background.
• No More Timeouts: Because a single call is time-boxed, you never hit the dreaded -32001 Request timed out. Long waits are handled by re-calling, not by holding one long request open.
• Fast Startup: The heavy Apify SDK is loaded lazily, so the MCP handshake completes in ~2 s.
• Smart Extraction: Built-in multi-strategy logic identifies verification codes and links (numeric, keyword-proximity, verification URL, custom regex, with a full-text fallback for the agent).
• Customizable: Optional tool prefixing supported via Actor configuration.

💡 Recommended Usage Pattern (important)

Do NOT keep the MCP server connected the whole time. Connect → create an email → do your registration → wait for the OTP → disconnect. Staying connected idle is expensive and increases failure rate. This Actor is designed for short, on-demand sessions and will auto-exit when idle.

---

🛠️ MCP Tools

Tool Name	Description	Key Inputs
create_email	Generates a new temporary email	provider (optional), username (optional)
list_inbox	Lists messages in the inbox	token, provider (optional)
wait_for_otp	Magic Tool: Waits up to ~45 s then extracts the code. Returns status: "pending" if nothing arrived yet — just call again.	token, pollingTimeoutSecs (optional, capped at 45), pollingIntervalSecs (optional), customRegex (optional), provider (optional)

---

🔌 Integration Guide & Agent Skills

🤖 Configuration for AI Agents (Roo Code, Claude, etc.)

Add this to your MCP settings. This command runs the Actor on Apify's infrastructure and tunnels the MCP protocol through Stdio.

{
  "mcpServers": {
    "tempmail-otp": {
      "command": "npx",
      "args": [
        "-y",
        "apify-cli",
        "actor:run",
        "rexreus/tempmail-otp-mcp",
        "--pipe",
        "-i",
        "{\"toolPrefix\": \"\", \"defaultProvider\": \"mail.tm\"}"
      ],
      "env": {
        "APIFY_TOKEN": "YOUR_APIFY_TOKEN"
      }
    }
  }
}

Note: The --pipe flag is essential for MCP to ensure stdio communication works correctly.

---

🧠 Agent Instructions: How to perform "OTP Flow"

If you are an AI Agent, read this carefully to understand your mission:

1. Identify available tools

Upon connection, you will see create_email, list_inbox, and wait_for_otp.

2. Execution Workflow

1. Action: Call create_email.
2. Analysis: Extract the address and token from the response.
   • Example Response: {"address": "xyz@mail.tm", "token": "SECRET_TOKEN"}
3. External Task: Use the address to register on the website you are currently browsing.
4. Action: Immediately call wait_for_otp with the token you saved.
   • Each call waits up to ~45 s (this stays safely under the MCP client's request timeout).
5. Logic:
   • If the tool returns an otp, submit it on the website.
   • If the tool returns status: "pending" (no mail yet), call wait_for_otp again with the same token. Repeat until you get the code or you decide to give up.
   • If the tool returns otp: null but gives you full_text, read the body and find the verification code yourself.
6. Finish: Once you have the OTP, disconnect. Do not keep the session open — it costs money and the server will auto-exit when idle anyway.

3. Creating multiple accounts

You can call create_email multiple times in a single session. Each call generates a unique identity. Always keep track of which token belongs to which address.

📝 Step-by-Step Example: Registering on Facebook

Here is a practical simulation of how an AI Agent handles a registration flow on Facebook using this MCP:

1. Initialize Session: The agent calls create_email to generate a temporary inbox:

   // Tool Call: create_email
   {}
   

   Response:

   {
     "address": "john.doe.7f3a@wshu.net",
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9..."
   }
   

2. Navigate & Fill Form: The agent navigates to the registration page (e.g., https://www.facebook.com/r.php) and inputs the registration details:

   • First name: John
   • Last name: Doe
   • Mobile number or email: john.doe.7f3a@wshu.net
   • Password: SecurePassword123!
   • Date of Birth & Gender The agent clicks the Sign Up button.

3. Await Verification Code: Facebook prompts for a 5-digit security code sent to the email. The agent immediately triggers wait_for_otp:

   // Tool Call: wait_for_otp
   {
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9..."
   }
   

   Response:

   {
     "subject": "12345 is your Facebook confirmation code",
     "otp": "12345",
     "strategy": "numeric"
   }
   

4. Complete Registration: The agent extracts the OTP code 12345 from the response, inputs it into the Facebook confirmation form, and submits it to successfully create the account. (If the first wait_for_otp had returned status: "pending", the agent would simply call it again with the same token until the code arrived, then disconnect.)

📋 Example Prompts for Users to Trigger the Agent

If you are a user, you can copy-paste these prompts directly into your AI Agent (equipped with this MCP) to execute automated sign-up tasks:

• General Sign-Up:

  "Register a new account on [WEBSITE_URL] using the tempmail-otp MCP server. Generate a temporary email, sign up on the page, poll the inbox for the OTP, submit it, and tell me the login credentials."

• Specific Provider Sign-Up:

  "Create a new profile on [WEBSITE_URL]. Call the create_email tool using the 'tempmail.lol' provider, then fill out the sign-up form, wait for the verification code using wait_for_otp, and complete the registration."

• Verification Link Flow (e.g., GitHub/Discord):

  "Go to [WEBSITE_URL] and start the registration process. Create a temp email address, use it to register, and wait for the verification email. If the server extracts a confirmation URL instead of a numeric code, follow that link to verify the account."

• Multiple Registrations:

  "Create 3 mock user accounts on [WEBSITE_URL] using different temporary email addresses. Track the generated email addresses and tokens, perform registration for each, and output a table containing the created emails and their registration status."

---

🛠️ Detailed Tool Reference

create_email

• Goal: Create a new session.
• Inputs: provider (mail.tm/tempmail.lol), username (optional).
• Output: Returns address and token.

wait_for_otp

• Goal: Poll (time-boxed) and parse the newest email.
• Inputs: token (required), pollingTimeoutSecs (optional, capped at 45 s), pollingIntervalSecs (optional), customRegex (optional).
• Output:
  • On success: { otp, subject, strategy }.
  • When no mail arrived within the window: { status: "pending", otp: null, message } → call again with the same token.
  • When mail arrived but the code could not be auto-detected: { otp: null, subject, full_text } → let the agent read full_text.

---

⚙️ Actor Configuration

Input Parameters (INPUT_SCHEMA.json)

• toolPrefix: Optional string to prepend to tool names (e.g., tm_ -> tm_create_email).
• defaultProvider: Default email provider to use (mail.tm or tempmail.lol).
• pollingTimeoutSecs: How long a single wait_for_otp call waits (default: 45). Capped at 45 s so it never exceeds the ~60 s MCP client request timeout; the agent re-calls while status is pending.
• idleTimeoutSecs: Auto-shutdown after this many seconds without any tool call, so an idle connection stops burning compute (default: 300, set 0 to disable).

Output Schema (Dataset)

For platform auditing, tool calls push a record to the Apify dataset (fire-and-forget, so it never slows down a tool call):

{
  "event": "otp_extracted",
  "provider": "mail.tm",
  "subject": "Your verification code",
  "otp": "185655",
  "strategy": "numeric",
  "success": "true"
}

Note on irregular OTPs: If the extraction logic cannot identify the OTP structure, the tool will return otp: null along with the full email body (full_text). AI Agents will easily extract it semantically from the text.

---

🛡️ Privacy

• Email accounts are ephemeral and provided by third-party temp mail services.
• Always use for temporary registrations only.

---

Built for the next generation of full AI automation.