otpkit
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@otpkit Create a temp email and wait for the verification code"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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
Providers
Email (all free, no API key)
Provider | Domain(s) | Privacy | Expiry | Method |
| grabmail.io, mixozia.com, linqmail.com | Private | None | REST |
| catchmail.io | Private | None | REST |
| guerrillamailblock.com + others | Private | ~1 hour | REST |
| 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 | 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 |
|
| |
|
|
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
No install needed (recommended)
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
From GitHub
pip install git+https://github.com/secfathy/otpkit.gitFrom 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 stopSetup
Claude Code (CLI)
Quickest — 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.
Claude Desktop (macOS / Windows)
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).
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)
Open VS Code → Cline sidebar → MCP Servers
Click Edit MCP Settings
Add:
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}Continue (VS Code / JetBrains)
Add to ~/.continue/config.yaml:
mcpServers:
- name: otpkit
command: otpkitZed
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 callAny 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.serverThe 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 claudeTools Reference
Email Tools
create_temp_email
Create a disposable email address.
Parameter | Type | Default | Description |
| string |
|
|
| string | random | Custom username prefix (e.g. |
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 |
| string | Email address created with |
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 |
| string | — | Email address to watch |
| int |
| Max seconds to wait (max 120) |
| int |
| 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 |
| string | Phone number from |
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 |
| string | — | Phone number to watch |
| int |
| Max seconds to wait (max 300) |
| int |
| 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 |
| string | — | Country code: |
| string | — | Target service: |
| string |
|
|
check_paid_sms
Check if an SMS arrived on a paid number.
Parameter | Type | Description |
| string | Order ID from |
Utility
extract_otp_from_text
Extract OTP codes and verification links from any text. Useful for processing messages from other sources.
Parameter | Type | Description |
| 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: stdioPython 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
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_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.
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"
otpkitOr 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 mcpRequirements
License
MIT
Available Tools
11 toolsbuy_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for e-mail testing: create disposable inboxes, wait for delivery, and extract e-mail content or links - all from your AI agent or test automation workflow. Get a free API key on https://app.zyntra.app/
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Disposable email inboxes for AI agents: create an address, wait for mail, read OTP codes and links.
Email and optional phone for AI agents: send, receive, search, draft and call over MCP.
Related MCP Servers
- AlicenseBqualityCmaintenanceDisposable 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.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create disposable email inboxes and automatically extract OTPs, magic links, and verification codes from incoming emails.10 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to generate temporary email addresses, receive emails, and automatically extract OTP codes and links from incoming messages for automation and testing workflows.MIT
- AlicenseNot gradedqualityBmaintenanceDisposable email for humans and AI agents. Enables AI agents to create mailboxes and receive verification emails through an MCP server.39MIT