An MCP server that creates disposable email addresses and phone numbers, checks their inboxes, and automatically extracts OTP codes and verification links from incoming messages.
Zero API keys required — every email provider and the free SMS source work without authentication.
- How It Works
- Providers
- Installation
- Setup
- Tools Reference
- Usage Examples
- Architecture
- Troubleshooting
- License
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:
- Create a temporary email address or get a free public phone number
- Wait for an incoming message (email or SMS)
- 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
| 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.
| 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.
| 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.
Use uvx to run directly from the repo — nothing to install:
uvx otpkit
uvxfetches and runs the package in an isolated environment. If you don't haveuv, install it:pip install uv
pip install git+https://github.com/secfathy/otpkit.gitgit clone https://github.com/secfathy/otpkit.git
cd otpkit
pip install -e .otpkit
# Server starts on stdio — press Ctrl+C to stopQuickest — install and register in one command (no clone needed):
claude mcp add otpkit -- uvx otpkitOr if you installed via pip:
claude mcp add otpkit -- otpkitOr using the Python module directly:
claude mcp add otpkit -- python -m src.serverTo verify it's registered:
claude mcp listNow 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.
- Open Claude Desktop settings
- Go to Developer → Edit Config
- Add otpkit to
claude_desktop_config.json:
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}- Restart Claude Desktop
The otpkit tools now appear in Claude's tool list (hammer icon).
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"],
"env": {
"FIVESIM_API_KEY": "your-key-here",
"SMSPOOL_API_KEY": "your-key-here"
}
}
}
}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.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}- Open VS Code → Cline sidebar → MCP Servers
- Click Edit MCP Settings
- Add:
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}Add to ~/.continue/config.yaml:
mcpServers:
- name: otpkit
command: otpkitAdd to Zed settings (settings.json):
{
"context_servers": {
"otpkit": {
"command": {
"path": "otpkit"
}
}
}
}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],
)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 callotpkit 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.serverThe server exposes 11 tools. Use your client's MCP configuration to point at the otpkit command.
If you use the Smithery MCP registry:
npx @smithery/cli install otpkit --client claudeCreate 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 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"]
}
]
}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 all email addresses created in this session.
Returns:
[
{
"address": "tmp1234567@grabmail.io",
"provider": "grabmail",
"age_seconds": 45
}
]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 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"]
}
]
}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) |
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 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 if an SMS arrived on a paid number.
| Parameter | Type | Description |
|---|---|---|
order_id |
string | Order ID from buy_temp_number |
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"]
}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]
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"]
}
You: Create a temp email with username "john.doe"
Agent:
1. create_temp_email(provider="grabmail", username="john.doe")
→ {"address": "john.doe@grabmail.io"}
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": []}
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"]}
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
mcpandhttpx
You must create an address with create_temp_email before checking it. Addresses only exist for the current session.
- grabmail / catchmail: Addresses are instant — if no messages appear, the sender hasn't delivered yet. Try
wait_for_emailwith 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.
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.
Set the environment variable before starting otpkit:
export FIVESIM_API_KEY="your-key"
otpkitOr pass it through your MCP client config (see Setup).
otpkit supports both MCP v1 and v2. If you see an import error, update the mcp package:
pip install --upgrade mcpMIT
