🚌 MockPost

Your app thinks it's talking to Stripe, Telegram, Twilio and Gmail… but it's MockPost.

MockPost is a local, multi-channel message emulator for end-to-end testing. Point your app's outbound credentials at MockPost and it captures every email, Telegram message, WhatsApp message, SMS, push notification, Slack/Discord webhook, Stripe event and OAuth session — while simulating realistic inbound events back to your app. All local, all deterministic, zero real credentials.

• Web panel — a unified timeline of every message across all channels, with per-channel detail, per-app filtering and a "Copy as Markdown" button.

• MCP server — an agent (Claude Code, OpenCode, Cursor, any MCP client) inspects the timeline, reads OTP codes and fires simulated events, all in one call.

• Zero config faking — your app keeps its real SDKs and its real-looking credentials; MockPost identifies each app by those credentials, so it never knows it's being faked.

Why? Real services mean accidental sends, third-party credentials, and agents that can't inspect what your app actually sent. MockPost makes message delivery observable.

Screenshots

Related MCP server: ldm-email-deliverability

Quick start

PyPI (once published)

pipx install mockpost        # or: uv tool install mockpost
mockpost                     # starts the server on :8090
# MCP server, for any harness:
pipx install mockpost && mockpost-mcp   # stdio MCP server

Docker (recommended)

docker run -p 8090:8090 -p 1025:1025 -v mockpost-data:/app/data ghcr.io/reiarseni/mockpost
# panel:      http://localhost:8090
# SMTP:       localhost:1025 (no auth)

From source

git clone https://github.com/reiarseni/mockpost
cd mockpost
uv venv && uv sync
uv run mockpost

60-second smoke test:

# send an email to your own machine
python -c "import smtplib; from email.mime.text import MIMEText; m=MIMEText('Your code is 123456'); m['Subject']='Verify'; m['From']='app@test.com'; m['To']='you@test.com'; smtplib.SMTP('localhost',1025).send_message(m)"

Then open http://localhost:8090 — the email is on the timeline, and get_latest_otp will find the code 123456.

What your app should point where

The /config page shows exact values plus copy-paste snippets per channel.

Inbound webhooks (back to your app): register your app's webhook in the panel (/webhooks) or via MCP register_webhook. Simulated inbound messages, status changes and signed Stripe events are POSTed to your app's URL — and every delivery (including the app's response body, even when it was down) is recorded in the timeline.

MCP integration

MockPost exposes an MCP server over stdio. Any harness that speaks MCP gets tools to inspect the timeline, read OTPs, and fire simulated events — so your agent can verify end-to-end behavior autonomously.

Prerequisite: the MockPost HTTP service must be running (default http://localhost:8090). The MCP server is a client of its internal API, so every tool call needs it up.

The MCP server ships with the repo and runs with python -m mcp_server.server (requires the Python deps from requirements.txt; MOCKPOST_URL defaults to http://localhost:8090).

Claude Code

Add to your project's .mcp.json (project-scoped) or ~/.claude.json / claude_desktop_config.json (user-scoped):

{
  "mcpServers": {
    "mockpost": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": { "MOCKPOST_URL": "http://localhost:8090" }
    }
  }
}

OpenCode

OpenCode supports MCP servers through its config (opencode.json / opencode.jsonc). Add the server under the mcp section:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mockpost": {
      "type": "local",
      "command": ["python", "-m", "mcp_server.server"],
      "environment": { "MOCKPOST_URL": "http://localhost:8090" },
      "enabled": true
    }
  }
}

Some OpenCode versions use "type": "stdio" instead of "type": "local" — use whichever your installed version accepts.

Any MCP harness (Cursor, Windsurf, VS Code, Continue, custom clients)

The universal contract is the same: run the server with command + args, pass env vars, done.

• VS Code (GitHub Copilot / MCP): mcp add mockpost -e "python" "-m" "mcp_server.server" or configure in .vscode/mcp.json / user settings under mcp.servers.

• Cursor: Settings → MCP → Add server → type command, command python -m mcp_server.server.

• Raw JSON (any stdio MCP client):

{
  "mcpServers": {
    "mockpost": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": { "MOCKPOST_URL": "http://localhost:8090" }
    }
  }
}

On Windows, wrap the command: "command": "cmd", "args": ["/c", "python", "-m", "mcp_server.server"].

What the agent can do

Typical agent flow:

1. set_app("my-app")                          # scope to your app
2. (your test runs and sends emails/messages)
3. get_timeline_markdown()                    # what did my app actually send?
4. get_latest_otp("user@test.com")            # the login code, parsed for you
5. simulate_incoming_message("whatsapp", ...) # now test the reply path
6. get_timeline_markdown()                    # verify the round trip

Per-app isolation (many apps testing at once)

Each app is identified by its fake credentials — it sends no extra headers, it never knows MockPost isn't the real service. Register the app once (panel /apps or MCP register_app):

Consequences:

• Captured messages are tagged with their app (panel filters by app).

• A webhook bound to an app only receives that app's simulated events.

• Unregistered credentials fall into the global queue.

Environment variables (all optional)

Emulated channels

Email (SMTP, no auth, MailHog-style) · Telegram Bot API (sendMessage/getUpdates/sendPhoto/setWebhook) · WhatsApp Cloud API (messages + statuses) · Web Push (real VAPID validation) · Twilio SMS (Messages.json + StatusCallback) · FCM · APNs · Slack · Discord · Stripe (checkout/payment_intents + signed Stripe-Signature events) · OTP (SMS/email/TOTP) · Fake OAuth2 for Google/GitHub/Facebook/X (JWT with local key) · Social webhooks (GitHub, Facebook, X) with per-provider signatures.

License

MIT — see LICENSE.