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](#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