otpkit
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Pass
- Code scan — Scanned 3 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
MCP server for temporary email & SMS — receive OTPs, verification links, and confirmation codes. Zero API keys required.
otpkit
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.
Table of Contents
- How It Works
- Providers
- Installation
- Setup
- Tools Reference
- Usage Examples
- Architecture
- Troubleshooting
- License
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 |
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
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.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)
- 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: 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" → [email protected]) |
Returns:
{
"address": "[email protected]",
"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": "[email protected]",
"provider": "grabmail",
"count": 1,
"messages": [
{
"id": "abc123",
"from": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]"}
2. [fills registration form with that email]
3. wait_for_email(address="[email protected]", 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": "[email protected]"}
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
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"
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
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found