Webhook.site MCP Server

Webhook.site MCP 服务

适用于 webhook.site 的模型上下文协议（MCP）服务，可即时捕获 HTTP 请求、电子邮件和 DNS 查询。非常适合测试 Webhook、调试 API 回调、安全测试和漏洞赏金狩猎。

安全辅助工具（SSRF、XSS、金丝雀令牌）仅用于获得授权的测试——仅限你拥有或明确获准测试的系统。

---

目录

• 快速开始
• 可以做什么？
• 工具参考
• 示例
• 每个 Webhook 令牌提供的功能
• 文档
• 开发
• 要求
• 贡献
• 致谢
• 链接

---

快速开始

安装

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

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

使用 3.0.0 或更高版本。2.1.3 无法在 MCP 2.0 上启动；3.0 重命名了几个工具（请参阅从 2.x 升级）。

VS Code / GitHub Copilot

添加到 .vscode/mcp.json：

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

Cursor

添加到 .cursor/mcp.json（项目配置）或你的用户 MCP 配置中：

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

Claude Desktop

添加到 claude_desktop_config.json：

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

配置

所有设置均为服务进程的环境变量。将它们放入 MCP 客户端配置的 env 区块中。

变量	用途
WEBHOOK_SITE_API_KEY	你的 webhook.site API 密钥。可使新 URL 永久有效（受你的套餐额度限制），并解锁 list_webhooks、Custom Actions、Schedules、Global Variables、Groups、Queue Profiles、Templates、Databases、Users 和 CSV 导出
WEBHOOK_SITE_DEFAULT_EXPIRY	未传入 expiry 时，新 URL 过期前的秒数。不设置时，付费账户中的 URL 永不过期（匿名 URL 为 7 天）
WEBHOOK_MCP_RATE_LIMIT_MAX_WAIT	webhook.site 返回 429 且 Retry-After 不超过此秒数（默认值为 15）时，调用会等待并重试一次；等待时间更长时，会报错并说明等待时长
FOLLOW_EMAIL_LINK_ALLOW_HOSTS	follow_email_link 仅打开指向公共互联网主机的链接，并连接到已检查的地址（不会遭受 DNS 重绑定攻击）。要在自己的机器或内网上测试注册流程，请列出允许的目标：localhost,127.0.0.1,*.corp.example,10.0.0.0/8
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	follow_email_link 会遵循这些设置。代理会建立连接，因此目标会在请求前进行检查，而不是固定到已检查的地址
SSL_CERT_FILE / SSL_CERT_DIR	用于 follow_email_link 的自定义 CA 证书包，适用于企业 TLS 拦截

如果验证链接请求成功完成，随后又重定向到不允许的目标（本地开发服务、内网控制面板），工具会报告该跳转的状态，并在 blocked_redirect 中注明被拒绝的目标，而不会失败：无论网站是否将其视为已验证，消耗令牌的请求都已经发出。

---

可以做什么？

捕获 Webhook

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

安全 / 漏洞赏金：

"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"

电子邮件自动化：

"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 测试：

"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"
"Hold the next request and answer it with a 402 and this JSON body"

### 实时监控：

"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"

数据分析：

"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"

使用你的账户自动化：

"Add a Custom Action that forwards every request to my staging API"
"Schedule a health check of https://example.com every 5 minutes and alert on a bad status"
"Write a WebhookScript that answers with the request's JSON field 'id'"

Canary Tokens

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

---

工具参考

匿名使用 7 天有效的 URL 时，无需账户即可使用所有功能。设置 WEBHOOK_SITE_API_KEY 后，URL 将永久有效，并且账户工具会解锁你所用套餐的功能。每个 webhook_token 都接受 UUID、别名、粘贴的 https://webhook.site/... URL 或收件箱地址。每个工具的完整参数请参阅：docs/TOOLS.md。

由服务通过 scripts/gen_tool_docs.py 生成，共 31 个工具。

诊断

工具	功能
server_status	检查此服务的配置：API 密钥、账户连通性、套餐、实时套接字和环境配置。

Webhook

工具	功能
create_webhook	创建一次性收件箱，用于在网站上注册：HTTP URL、临时邮箱、DNS。
configure_webhook	使用自定义设置创建 Webhook，或更新现有 Webhook（传入 webhook_token）。
get_webhook_info	显示 Webhook 的设置、到期时间、请求数和所有地址。
get_webhook_email	返回用于注册、验证、魔法链接或重置密码的临时收件箱。
list_webhooks	列出账户中的 Webhook（URL / 收件箱）。需要 WEBHOOK_SITE_API_KEY。
delete_webhook	永久删除 Webhook 及其捕获的所有请求和邮件。

请求

工具	功能
send_requests	向 Webhook URL 发送一个 JSON 请求体（data）或多个请求体（payloads），以测试捕获功能。
get_webhook_requests	分页列出 Webhook 捕获的 HTTP、邮件或 DNS 事件。
search_requests	按方法、正文文本、标头、类型或日期搜索捕获的事件。
get_request	返回一条捕获的事件：默认返回最新事件，也可通过 request_id 指定。
update_request	为捕获的请求添加备注，或设置其动态响应。
download_request_file	通过 file_id 下载上传的文件或邮件附件（base64）。
delete_request	按请求 ID 删除一条捕获的 HTTP、邮件或 DNS 事件。
delete_all_requests	清除 Webhook 上捕获的事件，可按日期或搜索查询筛选。
export_webhook_data	完整导出捕获的事件，包含 HTML 和未截断的正文，格式为 JSON 或 CSV。

实时

工具	功能
wait_for_request	等待新的 HTTP（或 DNS）回调到达 Webhook（1-120 秒）。
wait_for_email	等待注册、验证、魔法链接或密码重置邮件（1-120 秒）。
respond_to_next_request	暂停到达 Webhook 的下一个请求，并使用你提供的状态码、标头和正文进行响应。
follow_email_link	打开捕获的注册邮件中的验证、魔法链接或重置 URL。

账户功能（API 密钥）

工具	功能说明
manage_custom_actions	管理自定义操作，webhook.site 会在每次请求或电子邮件发送到某个令牌时运行这些操作。
manage_schedules	管理计划任务：webhook.site 会按指定间隔调用 request_url（需要 API 密钥）。
manage_global_variables	管理供所有 URL 共用的全局变量，可在自定义操作和计划任务中用作 $name$。
manage_groups	管理用于整理账户 Webhook 的群组（需要 API 密钥）。
manage_queues	管理用于限制排队自定义操作的队列配置（需要 API 密钥）。
manage_templates	管理模板：可重复使用的自定义操作集合及预定义变量（需要 API 密钥）。
manage_databases	管理 webhook.site 数据库并对其运行 SQL（需要 API 密钥）。
manage_users	管理 Enterprise 账户中的团队用户（需要管理员 API 密钥）。

安全测试

工具	功能说明
generate_oob_payloads	构建经授权的带外载荷，以便向此 Webhook 发送回连：SSRF URL、XSS 回调或金丝雀令牌。
check_for_callbacks	查看过去 N 分钟内是否收到 SSRF、XSS 或金丝雀回调。
extract_links_from_request	从捕获的电子邮件或 HTTP 正文中提取确认、重置、魔法链接及其他 URL。

从 2.x 升级

2.x 工具	3.0 替代项
create_webhook_with_config, update_webhook	configure_webhook（传入 webhook_token 进行更新）
get_webhook_url, get_webhook_dns	get_webhook_info 的字段
get_latest_request	get_request
send_to_webhook, send_multiple_requests	send_requests（data 或 payloads）
generate_ssrf_payload, generate_xss_callback, generate_canary_token	generate_oob_payloads（kind=ssrf|xss|canary、canary_type）

---

示例

在网站上注册

1. create_webhook — 获取 email（{token}@emailhook.site）
2. 在网站上使用该地址（注册、验证、魔法链接或重置密码）
3. wait_for_email — 接收邮件、确认 / 登录 / 重置 URL，以及任何 OTP
4. 使用 follow_email_link 打开验证链接，或在网站上输入 verification_codes

如果你已有令牌，get_webhook_email 会返回同一个收件箱。

创建 Webhook

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

等待密码重置邮件

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

轮询新事件，不进行分页

// get_webhook_requests(webhook_token, since=<next_since from the previous call>)
{
  "requests": [ ... only what arrived after the cursor ... ],
  "next_since": 1788472548944304
}

SSRF 测试载荷

// Response from generate_oob_payloads(kind="ssrf")
{
  "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"
  }
}

---

文档

页面	内容
docs/TOOLS.md	每个工具的参数和提示，内容由服务生成
docs/webhook-site-notes.md	webhook.site 的实际功能（已在线验证），包括官方文档有误之处
docs/testing.md	四个测试层、录制、验证脚本、模型评估、账户安全
docs/releasing.md	版本递增、打标签、发布工作流
CHANGELOG.md	版本历史

---

开发

git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"
pytest -m "not live and not live_auth"     # offline suite incl. replay of recorded live exchanges
python server.py                            # run the server on stdio

离线测试套件会重放真实录制的 webhook.site 交互；实时工具检查以及 live / live_auth 层级会调用真实 API。详情请参阅 docs/testing.md。

目录结构：server.py（入口和生命周期）、handlers/tools.py（工具注册）、services/（每个 API 区域对应一个模块）、utils/（HTTP 客户端、实时套接字、URL 安全、引用）、scripts/（实时检查、生成器、验证器）、evals/（模型参与的提示词）。

---

要求

• Python 3.10+
• mcp >= 2.0.0
• httpx >= 0.26.0、httpcore >= 1.0.0、anyio >= 4.0.0
• python-socketio[asyncio_client] >= 5.11.0（用于实时等待；没有它时，工具会回退到轮询）

---

贡献

欢迎提交 Bug 报告和 PR。每个 PR 只做一项更改，添加一个预期结果已根据真实 API 检查过的测试（参见 docs/testing.md），修改工具后运行 python scripts/gen_tool_docs.py。

---

致谢

• Simon Fredsted（webhook.site 创始人）
• webhook.site 官方开源仓库

本项目与 webhook.site 无关，也未获得其认可。

链接

• 📦 PyPI 软件包
• 🐙 GitHub 仓库
• 🌐 webhook.site - 本 MCP 封装的服务
• 📖 Model Context Protocol - MCP 规范

---

为 MCP 社区倾心打造 ❤️