Skip to main content
Glama

Zero API keys required — every email provider and the free SMS source work without authentication.


Table of Contents


Related MCP server: courier-mcp

How It Works

otpkit runs as an MCP (Model Context Protocol) server. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, or your own agent — can call its tools to:

  1. Create a temporary email address or get a free public phone number

  2. Wait for an incoming message (email or SMS)

  3. Receive the message with OTP codes and verification links already extracted

Agent                          otpkit                         Provider
  │                              │                              │
  ├─ create_temp_email() ───────►│                              │
  │◄─ {"address": "x@grab..."}──┤                              │
  │                              │                              │
  │   [uses address to sign up on a website]                    │
  │                              │                              │
  ├─ wait_for_email() ──────────►│──── poll every 5s ──────────►│
  │                              │◄─── new message ─────────────┤
  │                              │                              │
  │                              │  extract OTPs + links        │
  │                              │                              │
  │◄─ {"otps": ["847291"]} ─────┤                              │
  │                              │                              │
  │   [enters OTP on the website]                               │

All extraction happens automatically — every message is scanned for:

  • OTP codes: 4–8 digit numbers (e.g. 847291, 1234, 98765432)

  • Verification links: URLs containing keywords like verify, confirm, activate, token, reset, login — ranked first in results


Providers

Email (all free, no API key)

Provider

Domain(s)

Privacy

Expiry

Method

grabmail

grabmail.io, mixozia.com, linqmail.com

Private

None

REST

catchmail

catchmail.io

Private

None

REST

guerrillamail

guerrillamailblock.com + others

Private

~1 hour

REST

maildrop

maildrop.cc

Public

None

GraphQL

Choosing a provider:

  • grabmail (default) — best all-round choice. Three domains, no expiry, clean REST API, works worldwide.

  • catchmail — same quality as grabmail, different domain. Good as a backup.

  • guerrillamail — private with session-based auth. Addresses expire after ~1 hour.

  • maildrop — anyone can read any inbox. Use only for non-sensitive tests.

SMS — Free (no auth)

Source

Site

Type

receive-sms-free.cc

receive-sms-free.cc

Public shared numbers

Warning: Free SMS numbers are publicly shared — anyone can see the messages. Never use them for real accounts or sensitive services.

SMS — Paid (optional, private numbers)

Provider

Env Variable

Site

5sim

FIVESIM_API_KEY

5sim.net

smspool

SMSPOOL_API_KEY

smspool.net

Paid providers give you a private temporary number that only you can read. Set the API key as an environment variable to enable them.


Installation

Use uvx to run directly from the repo — nothing to install:

uvx otpkit

uvx fetches and runs the package in an isolated environment. If you don't have uv, install it: pip install uv

From GitHub

pip install git+https://github.com/secfathy/otpkit.git

From source

git clone https://github.com/secfathy/otpkit.git
cd otpkit
pip install -e .

Verify installation

otpkit
# Server starts on stdio — press Ctrl+C to stop

Setup

Claude Code (CLI)

Quickest — install and register in one command (no clone needed):

claude mcp add otpkit -- uvx otpkit

Or if you installed via pip:

claude mcp add otpkit -- otpkit

Or using the Python module directly:

claude mcp add otpkit -- python -m src.server

To verify it's registered:

claude mcp list

Now in any Claude Code session you can say:

"Create a temp email and wait for the verification code"

Claude will call create_temp_email, wait_for_email, and return the OTP automatically.

Claude Desktop (macOS / Windows)

  1. Open Claude Desktop settings

  2. Go to Developer → Edit Config

  3. Add otpkit to claude_desktop_config.json:

{
  "mcpServers": {
    "otpkit": {
      "command": "uvx",
      "args": ["otpkit"]
    }
  }
}
  1. Restart Claude Desktop

The otpkit tools now appear in Claude's tool list (hammer icon).

Claude Desktop with paid SMS

{
  "mcpServers": {
    "otpkit": {
      "command": "uvx",
      "args": ["otpkit"],
      "env": {
        "FIVESIM_API_KEY": "your-key-here",
        "SMSPOOL_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "otpkit": {
      "command": "uvx",
      "args": ["otpkit"]
    }
  }
}

Restart Cursor. The tools appear in Cursor's MCP panel.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "otpkit": {
      "command": "uvx",
      "args": ["otpkit"]
    }
  }
}

Cline (VS Code)

  1. Open VS Code → Cline sidebar → MCP Servers

  2. Click Edit MCP Settings

  3. Add:

{
  "mcpServers": {
    "otpkit": {
      "command": "uvx",
      "args": ["otpkit"]
    }
  }
}

Continue (VS Code / JetBrains)

Add to ~/.continue/config.yaml:

mcpServers:
  - name: otpkit
    command: otpkit

Zed

Add to Zed settings (settings.json):

{
  "context_servers": {
    "otpkit": {
      "command": {
        "path": "otpkit"
      }
    }
  }
}

OpenAI Agents SDK

from openai_agents import Agent, MCPServerStdio

otpkit = MCPServerStdio(command="otpkit")

agent = Agent(
    name="signup-agent",
    instructions="Use otpkit to create temp emails and extract OTPs.",
    mcp_servers=[otpkit],
)

Claude API (Anthropic SDK) with MCP

import anthropic
from anthropic.types import MCPServerStdio

client = anthropic.Anthropic()

server = MCPServerStdio(command="otpkit")

# Use with tool_use in Messages API
# The server exposes 11 tools that Claude can call

Any MCP Client (Generic)

otpkit uses stdio transport — it reads JSON-RPC from stdin and writes to stdout. Any MCP-compatible client can use it:

# Command to run:
otpkit

# Or with Python directly:
python -m src.server

The server exposes 11 tools. Use your client's MCP configuration to point at the otpkit command.

Smithery Registry

If you use the Smithery MCP registry:

npx @smithery/cli install otpkit --client claude

Tools Reference

Email Tools

create_temp_email

Create a disposable email address.

Parameter

Type

Default

Description

provider

string

"grabmail"

grabmail | catchmail | guerrillamail | maildrop

username

string

random

Custom username prefix (e.g. "john" → john@grabmail.io)

Returns:

{
  "address": "tmp1234567@grabmail.io",
  "provider": "grabmail",
  "domains": ["grabmail.io", "mixozia.com", "linqmail.com"]
}

check_email

Check inbox for new messages. Every message is automatically enriched with extracted OTPs and links.

Parameter

Type

Description

address

string

Email address created with create_temp_email

Returns:

{
  "address": "tmp1234567@grabmail.io",
  "provider": "grabmail",
  "count": 1,
  "messages": [
    {
      "id": "abc123",
      "from": "noreply@example.com",
      "subject": "Verify your email",
      "body": "Your verification code is 847291",
      "otps": ["847291"],
      "links": ["https://example.com/verify?token=xyz"]
    }
  ]
}

wait_for_email

Block until a new email arrives or timeout. Polls automatically.

Parameter

Type

Default

Description

address

string

—

Email address to watch

timeout

int

60

Max seconds to wait (max 120)

poll_interval

int

5

Seconds between polls (min 3)

Returns (on success):

{
  "status": "received",
  "waited_seconds": 12,
  "from": "noreply@example.com",
  "subject": "Verify your email",
  "body": "Your code is 847291",
  "otps": ["847291"],
  "links": ["https://example.com/verify?token=xyz"]
}

Returns (on timeout):

{
  "status": "timeout",
  "waited_seconds": 60
}

list_temp_emails

List all email addresses created in this session.

Returns:

[
  {
    "address": "tmp1234567@grabmail.io",
    "provider": "grabmail",
    "age_seconds": 45
  }
]

SMS Tools — Free

list_free_sms_numbers

List available public phone numbers for receiving SMS. No parameters needed.

Returns:

{
  "source": "receive-sms-free.cc",
  "count": 24,
  "numbers": [
    {"phone": "12543207594", "country": "USA"},
    {"phone": "447700900000", "country": "UK"}
  ],
  "warning": "Public shared numbers — anyone can read messages"
}

read_free_sms

Read recent SMS messages on a public number. Each message is scanned for OTP codes.

Parameter

Type

Description

phone

string

Phone number from list_free_sms_numbers

Returns:

{
  "phone": "12543207594",
  "source": "receive-sms-free.cc",
  "count": 20,
  "messages": [
    {
      "from": "19543583114",
      "text": "Your Uber code is 4829",
      "date": "2 min ago",
      "otps": ["4829"]
    }
  ]
}

wait_for_sms

Poll until a new SMS arrives on a free public number or timeout.

Parameter

Type

Default

Description

phone

string

—

Phone number to watch

timeout

int

120

Max seconds to wait (max 300)

poll_interval

int

10

Seconds between polls (min 5)

SMS Tools — Paid

get_sms_providers

List all SMS providers and whether they are configured.

Returns:

[
  {"name": "receive-sms-free", "type": "free", "auth": "none", "ready": true},
  {"name": "5sim", "type": "paid", "env_var": "FIVESIM_API_KEY", "ready": false},
  {"name": "smspool", "type": "paid", "env_var": "SMSPOOL_API_KEY", "ready": false}
]

buy_temp_number

Buy a private temporary phone number.

Parameter

Type

Default

Description

country

string

—

Country code: "russia", "usa", "india", etc.

service

string

—

Target service: "telegram", "whatsapp", "google", "any"

provider

string

"5sim"

5sim | smspool

check_paid_sms

Check if an SMS arrived on a paid number.

Parameter

Type

Description

order_id

string

Order ID from buy_temp_number

Utility

extract_otp_from_text

Extract OTP codes and verification links from any text. Useful for processing messages from other sources.

Parameter

Type

Description

text

string

Any text to scan

Returns:

{
  "otps": ["847291"],
  "links": ["https://example.com/verify?token=abc123"]
}

Usage Examples

Sign up for a website

You: Create a temp email, sign up on example.com, and get the verification code

Agent:
1. create_temp_email(provider="grabmail")
   → {"address": "tmp1794926042@grabmail.io"}

2. [fills registration form with that email]

3. wait_for_email(address="tmp1794926042@grabmail.io", timeout=60)
   → {
       "status": "received",
       "otps": ["847291"],
       "links": ["https://example.com/verify?token=abc123def"]
     }

4. [enters OTP 847291 on the website]

Get an SMS verification code

You: Get a phone number and wait for the Telegram verification code

Agent:
1. list_free_sms_numbers()
   → {"count": 24, "numbers": [{"phone": "12543207594", "country": "USA"}, ...]}

2. [uses 12543207594 as the phone number on Telegram]

3. wait_for_sms(phone="12543207594", timeout=120)
   → {
       "status": "received",
       "text": "Telegram code: 48291",
       "otps": ["48291"]
     }

Use a custom email username

You: Create a temp email with username "john.doe"

Agent:
1. create_temp_email(provider="grabmail", username="john.doe")
   → {"address": "john.doe@grabmail.io"}

Extract OTP from arbitrary text

You: What's the OTP in "Your verification code is 482917. It expires in 10 minutes."

Agent:
1. extract_otp_from_text(text="Your verification code is 482917. It expires in 10 minutes.")
   → {"otps": ["482917"], "links": []}

Private SMS with paid provider

You: Buy a private US number for WhatsApp verification

Agent:
1. get_sms_providers()
   → [... {"name": "5sim", "ready": true} ...]

2. buy_temp_number(country="usa", service="whatsapp", provider="5sim")
   → {"order_id": "12345", "phone": "+12025551234"}

3. [uses +12025551234 on WhatsApp]

4. check_paid_sms(order_id="12345")
   → {"status": "RECEIVED", "otps": ["583921"]}

Architecture

otpkit (MCP Server)
├── Email Backends
│   ├── grabmail.io    ─── REST API, no auth
│   ├── catchmail.io   ─── REST API, no auth
│   ├── guerrillamail  ─── REST API, session-based
│   └── maildrop.cc    ─── GraphQL, no auth
├── SMS Backends
│   ├── receive-sms-free.cc  ─── HTML scraper, no auth
│   ├── 5sim.net             ─── REST API, API key (optional)
│   └── smspool.net          ─── REST API, API key (optional)
├── Extraction Engine
│   ├── OTP regex: 4-8 digit codes
│   └── Link scorer: verification keywords ranked first
└── MCP Transport: stdio
  • Python 3.10+ with async/await throughout

  • httpx for all HTTP requests (async, connection pooling)

  • mcp SDK — compatible with both v1 (FastMCP) and v2 (MCPServer)

  • No database — session state is in-memory only

  • No dependencies beyond mcp and httpx


Troubleshooting

"Unknown address" error

You must create an address with create_temp_email before checking it. Addresses only exist for the current session.

No messages showing up

  • grabmail / catchmail: Addresses are instant — if no messages appear, the sender hasn't delivered yet. Try wait_for_email with a longer timeout.

  • guerrillamail: Addresses expire after ~1 hour. Create a new one if expired.

  • maildrop: Public inbox — if someone else is using the same username, you'll see their messages too.

SMS numbers return 0 messages

Free SMS numbers are scraped from a public site. If the site layout changes or the number has no recent messages, results may be empty. Try a different number from list_free_sms_numbers.

Paid SMS "API key not set"

Set the environment variable before starting otpkit:

export FIVESIM_API_KEY="your-key"
otpkit

Or pass it through your MCP client config (see Setup).

MCP import error

otpkit supports both MCP v1 and v2. If you see an import error, update the mcp package:

pip install --upgrade mcp

Requirements


License

MIT

Available Tools

11 tools
buy_temp_numberA

Buy a private temporary phone number (paid, requires API key in env).

Args: country: Country code — e.g. "russia", "usa", "india". service: Target service — e.g. "telegram", "whatsapp", "google", "any". provider: 5sim | smspool

Inputs: country (required), service (required), provider. Returns: result

check_emailA

Check inbox for new messages. Auto-extracts OTP codes and verification links.

Args: address: Temp email address to check.

Returns: JSON with messages, each containing extracted otps[] and links[].

Inputs: address (required). Returns: result

check_paid_smsB

Check if an SMS arrived on a paid temporary number.

Args: order_id: Order ID from buy_temp_number.

Inputs: order_id (required). Returns: result

create_temp_emailB

Create a temporary email address. All providers are free with no API key.

Args: provider: grabmail | catchmail | guerrillamail | maildrop username: Custom username prefix. Random if omitted.

Returns: JSON with the new address and provider name.

Inputs: provider, username. Returns: result

extract_otp_from_textB

Extract OTP codes (4-8 digits) and verification links from any text.

Args: text: Raw text to scan — email body, SMS content, HTML, etc.

Inputs: text (required). Returns: result

get_sms_providersA

List all SMS providers and their configuration status.

Inputs: no named parameters. Returns: result

list_free_sms_numbersA

List available free public phone numbers for receiving SMS. No auth needed.

Returns: JSON with available phone numbers from receive-sms-free.cc. These are shared public numbers — anyone can read messages.

Inputs: no named parameters. Returns: result

list_temp_emailsA

List all temporary email addresses created in this session.

Inputs: no named parameters. Returns: result

read_free_smsA

Read recent SMS messages on a free public phone number. No auth needed.

Args: phone: Phone number (digits only, from list_free_sms_numbers).

Inputs: phone (required). Returns: result

wait_for_emailA

Poll until a new email arrives or timeout.

Args: address: Temp email address to watch. timeout: Max seconds to wait (default 60, max 120). poll_interval: Seconds between polls (default 5, min 3).

Returns: JSON with the new message including extracted otps[] and links[], or timeout status.

Inputs: address (required), timeout, poll_interval. Returns: result

wait_for_smsA

Poll until a new SMS arrives on a free public number or timeout.

Args: phone: Phone number to watch. timeout: Max seconds to wait (default 120, max 300). poll_interval: Seconds between polls (default 10, min 5).

Inputs: phone (required), timeout, poll_interval. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools are clearly partitioned by channel (temp email, free SMS, paid SMS) and action (create, list, check, wait, buy). check_email vs wait_for_email and read_free_sms vs wait_for_sms could be momentarily confused, but descriptions clearly distinguish one-shot reads from polling.

    Naming Consistency4/5

    Nearly all tools follow a verb_noun snake_case pattern (create_temp_email, read_free_sms, buy_temp_number). Minor inconsistency: the object is sometimes 'temp_email' and sometimes just 'email', and free/paid qualifiers are applied inconsistently, but the pattern remains readable.

    Tool Count5/5

    11 tools is well within the ideal 3-15 range and each maps to a distinct step in the OTP acquisition workflow. No obviously redundant or filler tools.

    Completeness4/5

    The surface covers the full lifecycle of receiving OTPs via email and SMS, plus a standalone extraction utility. Minor gaps: no deletion/cleanup of temp addresses, no listing of existing paid orders/numbers, and no provider configuration setter (only get_sms_providers status).

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Disposable email MCP server for autonomous AI agents. Create labeled temporary inboxes, wait for verification emails, extract OTP codes and confirmation links — zero human intervention required.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.
      10 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Disposable email for humans and AI agents. Enables AI agents to create mailboxes and receive verification emails through an MCP server.
      39
      MIT