UnblockingAPI

@unblockingapi/mcp

适用于 UnblockingAPI 的官方 Model Context Protocol 服务和 Claude Code 插件。让 AI 应用（Claude、Cursor、VS Code、Lovable、Replit，……）能够通过轮换住宅代理访问真正的浏览器：抓取受机器人防护且大量使用 JavaScript 的网页，并将已发布模板涵盖的任意网站解析为结构化 JSON。

托管于 https://mcp.unblockingapi.com/mcp——将其添加为连接器并登录，无需安装。也可以通过 npx -y @unblockingapi/mcp 在本地运行。

工具

工具	功能	费用
unblock_fetch	抓取会阻止简单请求的公开网页，并返回整洁的 Markdown 或 HTML。它会自动为每个网站选择普通 HTTP 或真实浏览器；传入 template 则返回结构化 JSON。还可通过 CSS select 缩小范围。	每次成功消耗 1 个点数；重新读取相同抓取结果免费
find_templates	查找可将网站解析为 JSON 的模板——可以按即将抓取的 URL、关键词或类别查找，并查看其输出结构。	免费
get_build_guide	提供使用普通 HTTP 和 REST API 构建应用的指南：API 参考、获取完整页面、模板和使用示例（排名追踪器、列表聚合器、价格监控器）。	免费

请求失败不收费。服务的指令、工具说明和每条响应中的备注会引导 Agent：让 API 选择普通抓取或浏览器；解析已知网站前先检查是否有模板；内容缺失时滚动页面或等待；编写调用 API 的代码前先阅读构建指南。

模板

模板可将页面转换为命名字段，而非标记语言。模板目录涵盖范围广泛——搜索引擎、交易平台、房产门户、公司注册信息库——任何人都可以通过编辑器发布模板。没有针对任何特定网站的特殊处理：所有模板，无论官方还是社区发布，都以相同方式使用。

find_templates(url: "https://www.google.com/search?q=…")   → kjellberg/google-search
unblock_fetch(url: "…", template: "kjellberg/google-search") → { query, results, related_searches }

find_templates 会向 API 发起请求，由 API 按照与模板库相同的方式，将 URL 与每个已发布模板的主机、路径和必需查询参数进行匹配（* 表示一个路径段，** 表示任意更深层路径；主机必须完全匹配，除非模式中使用 *. 或 .*），因此即使目录不断扩大，也能找到匹配项。结果超过单次返回上限时，响应会附带 page，供你请求下一页。

如果网站发生变化导致解析器失败，系统会返回原始 HTML，并附带 parse_error: true，而不是报错。

工具背后的 API 端点

工具	调用	密钥
unblock_fetch	POST https://api.unblockingapi.com/unblock（JSON 请求体；template 用于选择模板）	X-Api-Key
find_templates	GET https://api.unblockingapi.com/templates.json?url=…&q=…&category=…&limit=…&page=…（公开目录，在服务端搜索；回答缓存 5 分钟）；若匹配项不超过 3 个，还会调用 GET https://app.unblockingapi.com/public/v1/templates/<handle>/<slug> 获取输出结构	无
get_build_guide	无：指南随包提供（guides/）	无

模板不是独立的端点：没有 /api/google-search 或 /api/<template>，只有设置了 template 的 /unblock。

已移除的工具

旧版本及从旧版本复制的工具列表中提到了一些已不存在的工具：

旧工具	移除版本	替代方式
google_search	0.4.0	find_templates(url: "https://www.google.com/search?q=…")，然后调用 unblock_fetch(url, template: "kjellberg/google-search")
list_templates	0.4.0	find_templates（现在也接受 url）
idealista_property	0.3.0	对 Idealista 页面调用 find_templates(url)，然后使用返回的模板调用 unblock_fetch
ahrefs_website_authority	0.2.0 之前（从未发布到 npm）	find_templates(url: "https://ahrefs.com/website-authority-checker/?input=example.com")

设置

你需要一个 UnblockingAPI 账户——前往 https://unblockingapi.com 注册（500 个免费额度，无需信用卡）。然后选择一种方式：

1. 托管服务——在应用中粘贴一个 URL 并登录。 无需安装，也无需复制密钥。推荐大多数应用使用。
2. Claude Code 插件——托管服务加上一个技能和设置命令，使用你的账户登录。
3. 在本地运行——通过 npx 使用 stdio 运行同一服务，适合喜欢自行运行的用户。

托管服务

https://mcp.unblockingapi.com/mcp

Streamable HTTP。支持 MCP 登录（OAuth）的应用只需提供 URL：它们会打开 UnblockingAPI 页面，你可以在其中登录并点击 Allow。应用永远不会看到你的密钥，你也可以随时在 app.unblockingapi.com 的 Settings → Connected apps 中断开连接。不支持登录的应用会将密钥作为 Authorization: Bearer <key>（或 X-Api-Key: <key>）发送。

应用	方式	指南
Claude.ai、Claude Desktop	Customize → Connectors → + Add → Add custom connector，粘贴 URL，然后点击 Connect	unblockingapi.com/tools/claude
Cursor	点击一次性链接，或在 ~/.cursor/mcp.json 中填写 "url"，然后在 Settings → MCP 下点击 Login	docs/cursor-setup.md · 网站
VS Code（Copilot）	code --add-mcp '{"name":"unblockingapi","type":"http","url":"https://mcp.unblockingapi.com/mcp"}'，首次使用时登录	网站
Windsurf	在 MCP 配置中填写 "serverUrl"（Cascade → MCPs → Open MCP config file）	网站
Lovable	Connectors → + → MCP server，OAuth	网站
Replit	Integrations → MCP Servers → + Add MCP server，然后点击 Test & save	网站
Bolt	Connectors → Manage connectors → Custom MCP server，传输方式选 HTTP，使用 MCP OAuth	网站
Zed	在 context_servers 下填写 "url"（和 "headers"）	网站
Cline	在 Remote Servers 标签页中设置 "type": "streamableHttp" 和密钥标头	网站
Gemini CLI / Antigravity	gemini mcp add --transport http … / "serverUrl" 加密钥标头	网站
Claude API	添加 mcp_servers 条目，并将你的密钥设为 authorization_token	网站
n8n	MCP Client Tool，HTTP Streamable，Bearer Auth	网站

使用密钥而非登录：

# Claude Code
claude mcp add --transport http unblockingapi https://mcp.unblockingapi.com/mcp \
  --header "Authorization: Bearer your_api_key_here"

{
  "mcpServers": {
    "unblockingapi": {
      "url": "https://mcp.unblockingapi.com/mcp",
      "headers": { "Authorization": "Bearer your_api_key_here" }
    }
  }
}

（部分应用将 URL 键称为 serverUrl 或 httpUrl；VS Code 使用 servers 和 "type": "http"。）Agent 框架：请参阅 Vercel AI SDK 和 LangChain。

Claude Code 插件

该插件会将 Claude Code 连接到托管服务，使用你的账户登录，并添加一个用于抓取和模板工作流的技能。在 Claude Code 中：

/plugin marketplace add unblockingapi/mcp
/plugin install unblockingapi@unblockingapi-plugins

然后运行 /mcp，选择 unblockingapi，再选择 Authenticate 登录。 如果你是新手，可以运行 /unblockingapi:setup，Claude 会引导你完成设置，然后检查是否正常运行。完整指南：docs/claude-setup.md。

在本地运行

通过 stdio 运行同一服务。需要 Node.js 18+，并在 UNBLOCKINGAPI_KEY 中设置你的密钥。

# Claude Code
claude mcp add unblockingapi -e UNBLOCKINGAPI_KEY=your_api_key_here -- npx -y @unblockingapi/mcp

# VS Code
code --add-mcp '{"name":"unblockingapi","command":"npx","args":["-y","@unblockingapi/mcp"],"env":{"UNBLOCKINGAPI_KEY":"your_api_key_here"}}'

Claude Desktop（claude_desktop_config.json；编辑后需重启）、Cursor （~/.cursor/mcp.json）以及大多数其他应用都可以使用此配置块：

{
  "mcpServers": {
    "unblockingapi": {
      "command": "npx",
      "args": ["-y", "@unblockingapi/mcp"],
      "env": { "UNBLOCKINGAPI_KEY": "your_api_key_here" }
    }
  }
}

可以自行编辑配置的 Agent 客户端也能根据你的请求完成设置： “安装 @unblockingapi/mcp MCP 服务。我的 API 密钥是 sk_xxx。它通过 npx -y @unblockingapi/mcp 使用 stdio 运行，并需要环境变量 UNBLOCKINGAPI_KEY。”

环境变量（本地服务）

变量	必填	默认值	用途
UNBLOCKINGAPI_KEY	是	—	你的 API 密钥。
UNBLOCKINGAPI_BASE_URL	否	https://api.unblockingapi.com	覆盖 API 基础 URL。
UNBLOCKINGAPI_TIMEOUT_MS	否	180000	每个请求的超时时间。普通 fetch 在回退到浏览器时可能需要约 170 秒。

用法

连接后，可以向你的 Agent 提出以下请求：

• “读取 https://example.com/pricing 并总结各个套餐。” → unblock_fetch(url) — 如果网站需要浏览器，API 会在浏览器中渲染页面
• “以 JSON 格式获取 ‘wikipedia’ 的 Google 搜索结果。” → find_templates(url) → unblock_fetch(url, template: "kjellberg/google-search")
• “这个网站有对应的模板吗？” → find_templates(url)
• “哪些内容可以解析为 JSON？” → find_templates(category: "real-estate")

unblock_fetch 参数

参数	类型	说明
url	string，必填	仅支持 http(s)；不接受媒体或二进制文件。
render	boolean	省略时由 API 决定（先尝试普通请求，在被阻止或遇到 JS 壳页面时使用浏览器；会按网站学习）。true 始终渲染，false 从不渲染。
location	string	代理所在国家/地区的 2 位代码（us、gb、de 等）。不支持的代码会被拒绝，并返回支持列表。
wait_for	string	使用浏览器。stable（默认值）、domcontentloaded、networkidle，或要等待的 CSS 选择器。
wait_state	enum	配合选择器 wait_for 使用：visible（默认值）、nonempty、hidden、stable。
scroll_steps	0–10	使用浏览器。在就绪检查前滚动指定次数（用于加载延迟内容）。
wait_min_ms	0–10000	使用浏览器。导航后的最短等待时间。
settle_ms	0–25000	使用浏览器。稳定等待时间上限（默认值为 5000）——DOM 静默 500 ms 后立即采集。
wait_rules	array	使用浏览器。[{if: "#consent", then: "#results"}] — 第一个可见的 if 条件生效，其 then 会替换 wait_for。
detect_ms	0–25000	使用浏览器。探测 wait_rules 的时长（默认值为 800）。
max_age	0–300	接受指定秒数内的缓存副本。命中缓存时会在 ms 内返回，并包含 cached: true。
template	string	使用已发布的模板解析（handle/name，或使用 handle/name@3 固定版本），并返回 JSON。会强制使用该模板的抓取设置。使用 find_templates 查找模板。
format	markdown | html	页面返回的格式（默认值为 markdown：内容大小仅为原来的一小部分）。模板结果始终为 JSON。
select	string	CSS 选择器：仅以 format 指定的格式返回匹配元素。
fresh	boolean	即使最近 10 分钟内已执行过完全相同的抓取，也重新抓取。默认情况下会复用该副本，因此使用其他 select 或 format 重新读取不会产生费用。
max_chars	integer	限制返回正文的长度（默认值为 120000），在应用 format/select 后生效。超出长度的正文会被截断并附带说明。

响应以 JSON 元数据块开头（job_id、status、http_response_code、 response_time_ms、render、render_reason、readiness、template_version、location、cached、parse_error、truncated 等）， 然后是后续操作建议（滚动以查看更多内容、使用范围更窄的 select 等），接着是 --- 以及 Markdown、HTML 或 JSON 正文。API 错误（密钥错误、额度用尽、 模板未知、参数无效、并发数超限）会以清晰的工具错误形式返回。

完整 API 参考文档：https://unblockingapi.com/docs。

开发

npm install
npm run dev        # tsx watch
npm run typecheck  # tsc --noEmit
npm run build      # compile to dist/
npm run smoke      # drive the built server over stdio (add UNBLOCKINGAPI_KEY for live fetches)
npm run smoke:http # the same over HTTP against dist/http.js (or MCP_URL=https://mcp.unblockingapi.com/mcp)
npm run start:http # the hosted server on :8080 (PORT)

仓库结构：src/（server.ts 工具、index.ts stdio 入口、 http.ts 托管入口、client.ts API 客户端）、Dockerfile（托管 镜像，由 .github/workflows/deploy.yml 部署到 mcp.unblockingapi.com）、.claude-plugin/（Claude Code 市场清单）、plugins/claude/（Claude Code 插件：托管服务、 技能、设置命令）、.cursor-plugin/ 和 plugins/cursor/（Cursor 插件）、docs/（设置指南）。

License

MIT