otpkit
<p align="center">
<img src="banner.png" alt="otpKit — MCP server for temporary email and SMS" width="100%">
</p>
<h1 align="center">otpkit</h1>
<p align="center">
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.
</p>
**Zero API keys required** — every email provider and the free SMS source work without authentication.
---
## Table of Contents
- [How It Works](#how-it-works)
- [Providers](#providers)
- [Installation](#installation)
- [Setup](#setup)
- [Tools Reference](#tools-reference)
- [Usage Examples](#usage-examples)
- [Architecture](#architecture)
- [Troubleshooting](#troubleshooting)
- [License](#license)
---
## How It Works
otpkit runs as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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](https://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](https://5sim.net) |
| `smspool` | `SMSPOOL_API_KEY` | [smspool.net](https://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:
```bash
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
```bash
pip install git+https://github.com/secfathy/otpkit.git
```
### From source
```bash
git clone https://github.com/secfathy/otpkit.git
cd otpkit
pip install -e .
```
### Verify installation
```bash
otpkit
# Server starts on stdio — press Ctrl+C to stop
```
---
## Setup
### Claude Code (CLI)
**Quickest — install and register in one command (no clone needed):**
```bash
claude mcp add otpkit -- uvx otpkit
```
Or if you installed via pip:
```bash
claude mcp add otpkit -- otpkit
```
Or using the Python module directly:
```bash
claude mcp add otpkit -- python -m src.server
```
To verify it's registered:
```bash
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`:
```json
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}
```
4. Restart Claude Desktop
The otpkit tools now appear in Claude's tool list (hammer icon).
### Claude Desktop with paid SMS
```json
{
"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`):
```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`:
```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:
```json
{
"mcpServers": {
"otpkit": {
"command": "uvx",
"args": ["otpkit"]
}
}
}
```
### Continue (VS Code / JetBrains)
Add to `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: otpkit
command: otpkit
```
### Zed
Add to Zed settings (`settings.json`):
```json
{
"context_servers": {
"otpkit": {
"command": {
"path": "otpkit"
}
}
}
}
```
### OpenAI Agents SDK
```python
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
```python
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:
```bash
# 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](https://smithery.ai) MCP registry:
```bash
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:**
```json
{
"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:**
```json
{
"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):
```json
{
"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):
```json
{
"status": "timeout",
"waited_seconds": 60
}
```
#### `list_temp_emails`
List all email addresses created in this session.
**Returns:**
```json
[
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
[
{"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:**
```json
{
"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:
```bash
export FIVESIM_API_KEY="your-key"
otpkit
```
Or pass it through your MCP client config (see [Setup](#setup)).
### MCP import error
otpkit supports both MCP v1 and v2. If you see an import error, update the `mcp` package:
```bash
pip install --upgrade mcp
```
---
## Requirements
- Python 3.10+
- [`mcp`](https://pypi.org/project/mcp/) >= 1.0.0
- [`httpx`](https://pypi.org/project/httpx/) >= 0.27.0
---
## License
MIT
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).