Webhook MCP Server

Webhook.site MCP Server

A Model Context Protocol (MCP) server for webhook.site - instantly capture HTTP requests, emails, and DNS lookups. Perfect for testing webhooks, debugging API callbacks, security testing, and bug bounty hunting.

Security helper tools (SSRF, XSS, canary tokens) are for authorized testing only — systems you own or have explicit permission to test.

---

Table of Contents

• Quick Start
• What Can You Do?
• Tools Reference
• Examples
• Each Webhook Token Provides
• Architecture
• Development
• Contributing
• Requirements
• Changelog
• Credits
• Links

---

Quick Start

Installation

# Using uvx (recommended - no install needed)
uvx webhook-mcp-server==2.2.2

# Or install via pip
pip install webhook-mcp-server==2.2.2

Use 2.2.2 or newer. 2.1.3 does not start on MCP 2.0.

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "webhook-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["webhook-mcp-server==2.2.2"]
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or your user MCP config:

{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": ["webhook-mcp-server==2.2.2"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": ["webhook-mcp-server==2.2.2"]
    }
  }
}

---

What Can You Do?

Capture Webhooks

"Create a webhook and show me the URL"
"What requests have been sent to my webhook?"
"Wait for a request to come in"

Security/Bug Bounty:

"Generate an SSRF payload to test for blind vulnerabilities"
"Create XSS callback payloads to detect blind XSS attacks"
"Make me a canary token to detect if someone accesses a URL"

Email Automation:

"Create a temp email and wait for a password reset link"
"Monitor this webhook for emails and extract all links from them"
"Give me 3 temporary emails at once" (batch creation)

API Testing:

"Create a webhook that returns a 404 error with a custom message"
"Make a webhook with CORS enabled that waits 5 seconds before responding"
"Send 10 different test requests to a webhook and show me all the captured data"

Real-time Monitoring:

"Create a webhook and wait for any HTTP request to arrive"
"Monitor for DNS lookups to detect if a server is making DNS queries"
"Search all requests for ones containing 'password' in the body"

Data Analysis:

"Export all captured webhook requests to JSON format"
"Show me statistics on requests received in the last hour"
"Filter and show only POST requests with specific headers"

Creative/Practical:

"Create a webhook that pretends to be a Stripe payment API"
"Make a fake login endpoint that captures credentials (for pentesting)"
"Set up an email inbox that auto-extracts verification codes"

Canary Tokens

"Create a canary URL to track document access"
"Generate a DNS canary for the config file"
"Set up an email tracker pixel"

---

Tools Reference

Webhook Management

Request Handling

Real-Time Waiting

Bug Bounty / Security

Batch & Utility

---

Examples

Sign up on a website

1. create_webhook — get email ({token}@email.webhook.site)
2. Use that address on the site (sign-up, verify, magic link, or password reset)
3. wait_for_email — receive the message, confirm / login / reset URLs, and any OTP
4. follow_email_link to open a verify link, or type verification_codes on the site

If you already have a token, get_webhook_email returns the same inbox.

Create a Webhook

// Response from create_webhook
{
  "token": "abc123-def456-...",
  "url": "https://webhook.site/abc123-def456-...",
  "email": "abc123-def456-...@email.webhook.site",
  "dns": "abc123-def456-....dnshook.site"
}

Wait for Password Reset Email

// Response from wait_for_email
{
  "email_received": true,
  "subject": "Password Reset Request",
  "from": "noreply@example.com",
  "auth_links": ["https://example.com/reset?token=xyz789"],
  "verification_codes": ["847291"]
}

SSRF Testing Payload

// Response from generate_ssrf_payload
{
  "payloads": {
    "http": "https://webhook.site/token?id=ssrf-test",
    "dns": "ssrf-test.token.dnshook.site",
    "ip_decimal": "http://2130706433/token",
    "ip_hex": "http://0x7f000001/token"
  }
}

---

Each Webhook Token Provides

---

Architecture

webhook-mcp-server/
├── server.py              # MCPServer entry point + lifespan
├── handlers/              # Typed @mcp.tool() registrations
├── services/              # Business logic
│   ├── webhook_service.py # Webhook CRUD
│   ├── request_service.py # Request management
│   └── bugbounty_service.py # Security payloads
├── models/                # Config / filter / result types
└── utils/                 # HTTP client, logging, validation

Key Features

• Async Architecture - Non-blocking I/O for optimal performance
• Retry Logic - Exponential backoff for transient failures
• Input Validation - UUID validation, parameter sanitization
• Structured Logging - JSON logs for debugging and monitoring
• Type Safety - Full type hints throughout

---

Development

Setup

git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"

Run Tests

# Offline unit tests (default for CI)
pytest -m "not live" -v

# Live webhook.site tests
pytest -m live -v

Run Locally

python server.py

---

Requirements

• Python 3.10+
• mcp >= 2.0.0
• httpx >= 0.25.0

---

Changelog

See CHANGELOG.md for version history.

---

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue describing the problem
2. Suggest features - Open an issue with your idea
3. Submit PRs - Fork the repo and submit a pull request

Development Setup

git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"
pytest -m "not live" -v

Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation as needed
• Keep PRs focused on a single change

---

Credits

• Simon Fredsted (Founder of webhook.site)
• Official webhook.site open source repo

This project is not affiliated with or endorsed by webhook.site

Links

• 📦 PyPI Package
• 🐙 GitHub Repository
• 🌐 webhook.site - The service this MCP wraps
• 📖 Model Context Protocol - MCP specification

---

Made with ❤️ for the MCP community