Busque páginas web protegidas por bots ou com muito JavaScript, ou transforme-as em JSON estruturado usando templates publicados.
Também conhecido como unblockingapi/mcp, mcp, @unblockingapi/mcp
- Stars
- 2
- Ferramentas
- 3
- Downloads, 30 dias
- —
- Versão mais recente
- 0.8.4
- Último commit
- 14 de nov. de 2026
- Licença
- MIT
O que é o MCP UnblockingAPI?
Busque páginas web protegidas por bots ou com muito JavaScript, ou transforme-as em JSON estruturado usando templates publicados. Ele expõe 3 ferramentas, como unblock_fetch, find_templates, get_build_guide.
Resumo gerado a partir do README do projeto
Sobre o MCP server de UnblockingAPI
O UnblockingAPI oferece uma maneira para aplicações de IA acessarem conteúdo web que normalmente é protegido por bots ou que exige JavaScript para renderização. Ele atua como uma ponte, fornecendo a clientes como Claude, Cursor e VS Code um ambiente de navegador real com suporte de proxies residenciais rotativos. Isso permite que desenvolvedores busquem Markdown ou HTML limpo de sites complexos ou transformem páginas web em dados JSON estruturados usando uma biblioteca de templates publicados.
Os usuários podem se conectar via um servidor hospedado usando login via OAuth para uma experiência sem instalação, ou executá-lo localmente usando npx. O servidor inclui ferramentas específicas como unblock_fetch para recuperar conteúdo de páginas, find_templates para localizar parsers existentes por URL ou categoria, e get_build_guide para documentação da API. Ele foi projetado para lidar com tarefas complexas de scraping, como monitoramento de preços ou listagens de imóveis, escolhendo automaticamente entre HTTP simples e um navegador completo com base nas necessidades do site alvo.
O que você pode fazer com ele
- 1Extrair dados estruturados de mecanismos de buscaUm agente de IA pode encontrar um template específico para um mecanismo de busca e, em seguida, buscar os resultados como um objeto JSON estruturado.
- 2Burlar proteções de bots em sites complexosDesenvolvedores podem solicitar uma URL e o sistema usará automaticamente um navegador real se o site bloquear requisições simples.
- 3Descobrir web scrapers existentesVocê pode pesquisar no catálogo de templates por palavra-chave ou categoria para ver se um site já pode ser convertido em JSON.
- 4Fazer o scrape de elementos específicos de uma páginaUm usuário pode restringir o conteúdo retornado fornecendo um seletor CSS para obter apenas partes específicas de uma página web.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Como instalar o MCP UnblockingAPI
Formatos verificados em 10 nov 2026Adicionar ao CursorAdicionar ao GooseInstalar o MCP UnblockingAPI no Claude Code
$ claude mcp add --env 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' mcp -- npx -y @unblockingapi/mcpInstalar o MCP UnblockingAPI no Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@unblockingapi/mcp"
],
"env": {
"UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
}
}
}
}Instalar o MCP UnblockingAPI no VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@unblockingapi/mcp"
],
"env": {
"UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
}
}
}
}Instalar o MCP UnblockingAPI no VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@unblockingapi/mcp"],"env":{"UNBLOCKINGAPI_KEY":"<YOUR_UNBLOCKINGAPI_KEY>"}}'Instalar o MCP UnblockingAPI no Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@unblockingapi/mcp"
],
"env": {
"UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
}
}
}
}Instalar o MCP UnblockingAPI no Codex
$ codex mcp add mcp --env 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' -- npx -y @unblockingapi/mcpInstalar o MCP UnblockingAPI no Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@unblockingapi/mcp"] [mcp_servers.mcp.env] UNBLOCKINGAPI_KEY = "<YOUR_UNBLOCKINGAPI_KEY>"
Instalar o MCP UnblockingAPI no Gemini CLI
$ gemini mcp add -s user -e 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' mcp npx -- -y @unblockingapi/mcpInstalar o MCP UnblockingAPI no Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@unblockingapi/mcp"
],
"env": {
"UNBLOCKINGAPI_KEY": "<YOUR_UNBLOCKINGAPI_KEY>"
}
}
}
}Iniciado pela HostedMCP em 16 de nov. de 2026
Rodamos este comando para @unblockingapi/mcp 0.8.4 em um contêiner isolado, sem rede e sem chaves. Ele respondeu e listou 3 ferramentas.
Ferramentas do MCP UnblockingAPI 3
Lido do servidor com tools/listunblock_fetchSomente leituraFetch a web page through UnblockingAPI's rotating residential proxies and a real browser. Useful for pages a plain HTTP fetch can't read: pages that need JavaScript, refuse automated requests, or show different content by country. Returns the page as Markdown (or cleaned HTML with format: 'html'); select narrows it to the part you need. If content is missing, fetch again with scroll_steps or wait_for. Picks the mode itself by default: a plain HTTP fetch first, and a real browser when the site blocks it or needs JavaScript. Pass a template reference to get structured JSON instead of HTML — call find_templates with the url first to see whether one exists. Costs 1 credit per successful fetch; failures are free.
find_templatesSomente leituraFind published templates that parse a site into structured JSON instead of HTML. Pass the url you are about to fetch to see whether one already covers it — do this before writing your own extraction for a well-known site. Also searches by keyword or category. Each result shows the fields it returns and an example call; pass its reference as unblock_fetch's template argument. Free — no credit is charged.
get_build_guideSomente leituraRead this before writing code that uses UnblockingAPI - an app, script, scheduled job or backend that fetches web pages (a rank tracker, a listings aggregator, a price monitor, …). Returns the REST API reference for calling it with plain HTTP (no SDK), how to keep the key server-side on platforms like Lovable, Replit and Next.js, how to use templates, and complete recipes. Free. Start with topic 'api', then the recipe that fits.
| unblock_fetch | Fetch a web page through UnblockingAPI's rotating residential proxies and a real browser. Useful for pages a plain HTTP fetch can't read: pages that need JavaScript, refuse automated requests, or show different content by country. Returns the page as Markdown (or cleaned HTML with format: 'html'); select narrows it to the part you need. If content is missing, fetch again with scroll_steps or wait_for. Picks the mode itself by default: a plain HTTP fetch first, and a real browser when the site blocks it or needs JavaScript. Pass a template reference to get structured JSON instead of HTML — call find_templates with the url first to see whether one exists. Costs 1 credit per successful fetch; failures are free. | Somente leitura |
| find_templates | Find published templates that parse a site into structured JSON instead of HTML. Pass the url you are about to fetch to see whether one already covers it — do this before writing your own extraction for a well-known site. Also searches by keyword or category. Each result shows the fields it returns and an example call; pass its reference as unblock_fetch's template argument. Free — no credit is charged. | Somente leitura |
| get_build_guide | Read this before writing code that uses UnblockingAPI - an app, script, scheduled job or backend that fetches web pages (a rank tracker, a listings aggregator, a price monitor, …). Returns the REST API reference for calling it with plain HTTP (no SDK), how to keep the key server-side on platforms like Lovable, Replit and Next.js, how to use templates, and complete recipes. Free. Start with topic 'api', then the recipe that fits. | Somente leitura |
Configuração
UNBLOCKINGAPI_KEYObrigatórioSecretoYour UnblockingAPI key from https://unblockingapi.com (500 free credits, no card).
UNBLOCKINGAPI_TIMEOUT_MSPer-request timeout in milliseconds. Default 180000.
| Nome | Descrição | Tipo |
|---|---|---|
| UNBLOCKINGAPI_KEY | Your UnblockingAPI key from https://unblockingapi.com (500 free credits, no card). | ObrigatórioSecreto |
| UNBLOCKINGAPI_TIMEOUT_MS | Per-request timeout in milliseconds. Default 180000. |
Verificações automatizadas
Executado em 16 de nov. de 2026Relatório completo →Passou em nossas verificações automatizadas. Isso não é uma auditoria de segurança: leia o código e dê ao servidor o acesso mais restrito de que ele precisa. Como as verificações funcionam
- Repositório de origem vinculado e acessívelunblockingapi/mcp is public and reachablegithub.com/unblockingapi/mcp ↗Passou
- O pacote indica este repositório como sua origem@unblockingapi/mcp names unblockingapi/mcp as sourcenpmjs.com/package/@unblockingapi/mcp ↗Passou
- Proveniência da build (atestação Sigstore)No build attestation published for this releaseNão verificado
- Licença de código aberto (OSI)MITspdx.org/licenses/MIT.html ↗Passou
- Commit ou release no último anoLast commit or release 2026-11-14github.com/unblockingapi/mcp ↗Passou
- OpenSSF ScorecardNão verificado
- Nome do pacote não é próximo a um pacote popularNo popular package one edit away from @unblockingapi/mcpPassou
- Nenhum aviso crítico no pacote ou em suas dependências121 resolved dependencies checked; no critical advisoryosv.dev ↗Passou
- Sem instruções ocultas para o modelo3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPassou
- Ferramentas destrutivas estão rotuladasNo tool named like delete, drop or execPassou
- O endpoint remoto responde ao handshake do MCPinitialize answered with protocol 2025-11-25 in 526 ms; tools/list returned 3 toolsPassou
README
Ver no GitHub@unblockingapi/mcp
Official Model Context Protocol server and Claude Code plugin for UnblockingAPI. Gives AI apps (Claude, Cursor, VS Code, Lovable, Replit, …) a real browser behind rotating residential proxies: fetch bot-protected and JavaScript-heavy pages, and parse any site a published template covers into structured JSON.
Hosted at https://mcp.unblockingapi.com/mcp — add it as a connector and
sign in, no install. Or run it locally with npx -y @unblockingapi/mcp.
Tools
| Tool | What it does | Cost |
|---|---|---|
unblock_fetch |
Fetch public web pages that block simple requests, and get clean Markdown or HTML back. Picks plain HTTP or a real browser per site by itself; pass template to get structured JSON instead. Optionally narrowed with a CSS select. |
1 credit per success; re-reading the same fetch is free |
find_templates |
Find a template that parses a site into JSON — by the URL you are about to fetch, by keyword, or by category — with its output shape. | free |
get_build_guide |
Guides for building apps on the REST API with plain HTTP: API reference, getting complete pages, templates, and recipes (rank tracker, listings aggregator, price monitor). | free |
Failed requests are free. The server's instructions, tool descriptions and the notes in each response steer the agent: let the API choose plain fetch or browser, check for a template before parsing a known site, scroll or wait when content is missing, and read the build guide before writing code that calls the API.
Templates
A template turns a page into named fields instead of markup. The catalogue is open-ended — search engines, marketplaces, property portals, company registries — and anyone can publish one from the editor. There is no special handling for any particular site: every template, official or community, is reached the same way.
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 asks the API, which matches the URL against every published
template's host, path and required query parameters the same way the template
library does (* is one path segment, ** any deeper path, hosts exact unless
the pattern says *. or .*), so a match is found however large the
catalogue grows. More results than fit come back with a page to ask for next.
If a parser fails because the site changed, you get raw HTML back with
parse_error: true rather than an error.
API endpoints behind the tools
| Tool | Calls | Key |
|---|---|---|
unblock_fetch |
POST https://api.unblockingapi.com/unblock (JSON body; template selects a template) |
X-Api-Key |
find_templates |
GET https://api.unblockingapi.com/templates.json?url=…&q=…&category=…&limit=…&page=… (the public catalogue, searched server-side; answers cached for 5 minutes), plus GET https://app.unblockingapi.com/public/v1/templates/<handle>/<slug> for the output shape when three or fewer match |
none |
get_build_guide |
nothing: the guides ship in the package (guides/) |
none |
Templates are not endpoints of their own: there is no /api/google-search or
/api/<template>, only /unblock with template set.
Removed tools
Older versions, and listings copied from them, mention tools that no longer exist:
| Old tool | Removed in | Use instead |
|---|---|---|
google_search |
0.4.0 | find_templates(url: "https://www.google.com/search?q=…"), then unblock_fetch(url, template: "kjellberg/google-search") |
list_templates |
0.4.0 | find_templates (now also takes url) |
idealista_property |
0.3.0 | find_templates(url) for the Idealista page, then unblock_fetch with the template it returns |
ahrefs_website_authority |
before 0.2.0 (never on npm) | find_templates(url: "https://ahrefs.com/website-authority-checker/?input=example.com") |
Setup
You need an UnblockingAPI account — sign up at https://unblockingapi.com (500 free credits, no card). Then pick one:
- Hosted server — paste one URL into your app and sign in. Nothing to install, no key to copy. Recommended for most apps.
- Claude Code plugin — the hosted server plus a skill and a setup command, signed in with your account.
- Run it locally — the same server over stdio with
npx, for those who prefer to run it themselves.
Hosted server
https://mcp.unblockingapi.com/mcp
Streamable HTTP. Apps that support MCP sign-in (OAuth) only need the URL: they
open an UnblockingAPI page where you sign in and click Allow. The app never
sees your key, and you can disconnect it any time under Settings → Connected
apps at app.unblockingapi.com. Apps without sign-in send your key as
Authorization: Bearer <key> (or X-Api-Key: <key>).
| App | How | Guide |
|---|---|---|
| Claude.ai, Claude Desktop | Customize → Connectors → + Add → Add custom connector, paste the URL, Connect | unblockingapi.com/tools/claude |
| Cursor | One-click link, or "url" in ~/.cursor/mcp.json, then Login under Settings → MCP |
docs/cursor-setup.md · site |
| VS Code (Copilot) | code --add-mcp '{"name":"unblockingapi","type":"http","url":"https://mcp.unblockingapi.com/mcp"}', sign in on first use |
site |
| Windsurf | "serverUrl" in the MCP config (Cascade → MCPs → Open MCP config file) |
site |
| Lovable | Connectors → + → MCP server, OAuth | site |
| Replit | Integrations → MCP Servers → + Add MCP server, Test & save | site |
| Bolt | Connectors → Manage connectors → Custom MCP server, transport HTTP, MCP OAuth | site |
| Zed | "url" (+ "headers") under context_servers |
site |
| Cline | Remote Servers tab, "type": "streamableHttp" + key header |
site |
| Gemini CLI / Antigravity | gemini mcp add --transport http … / "serverUrl" + key header |
site |
| Claude API | mcp_servers entry, your key as authorization_token |
site |
| n8n | MCP Client Tool, HTTP Streamable, Bearer Auth | site |
With a key instead of signing in:
# 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" }
}
}
}
(Some apps name the URL key serverUrl or httpUrl; VS Code uses servers
with "type": "http".) Agent frameworks: see
Vercel AI SDK and LangChain.
Claude Code plugin
The plugin connects Claude Code to the hosted server, signed in with your account, and adds a skill for the fetch and template workflow. In Claude Code:
/plugin marketplace add unblockingapi/mcp
/plugin install unblockingapi@unblockingapi-plugins
Then run /mcp, pick unblockingapi and choose Authenticate to sign in.
New to this? Run /unblockingapi:setup and Claude walks you through it, then
checks that it works. Full walkthrough: docs/claude-setup.md.
Run it locally (non-Claude MCP clients)
The same server over stdio for Cursor, VS Code, Claude Desktop's local config,
and other MCP hosts. Needs Node.js 18+ and your key in UNBLOCKINGAPI_KEY.
Claude Code should use the plugin (hosted OAuth) instead
of this env-var path.
# VS Code
code --add-mcp '{"name":"unblockingapi","command":"npx","args":["-y","@unblockingapi/mcp"],"env":{"UNBLOCKINGAPI_KEY":"your_api_key_here"}}'
Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json;
restart after editing) and most other apps take this block:
{
"mcpServers": {
"unblockingapi": {
"command": "npx",
"args": ["-y", "@unblockingapi/mcp"],
"env": { "UNBLOCKINGAPI_KEY": "your_api_key_here" }
}
}
}
Agentic clients that edit their own config will also set it up if you ask:
"Install the @unblockingapi/mcp MCP server. My API key is sk_xxx. It runs over
stdio via npx -y @unblockingapi/mcp and needs the env var UNBLOCKINGAPI_KEY."
Environment variables (local server)
| Var | Required | Default | Purpose |
|---|---|---|---|
UNBLOCKINGAPI_KEY |
yes | — | Your API key. |
UNBLOCKINGAPI_BASE_URL |
no | https://api.unblockingapi.com |
Override the API base URL. |
UNBLOCKINGAPI_TIMEOUT_MS |
no | 180000 |
Per-request timeout. A plain fetch that falls back to a browser can take ~170 s. |
Usage
Once connected, ask your agent things like:
- "Read https://example.com/pricing and summarise the plans."
→
unblock_fetch(url)— the API renders it in a browser if the site needs one - "Get the Google results for 'wikipedia' as JSON."
→
find_templates(url)→unblock_fetch(url, template: "kjellberg/google-search") - "Is there a template for this site?" →
find_templates(url) - "What can this parse into JSON?" →
find_templates(category: "real-estate")
unblock_fetch parameters
| Param | Type | Notes |
|---|---|---|
url |
string, required | http(s) only; media/binary files are rejected. |
render |
boolean | Omit to let the API decide (plain first, browser when blocked or a JS shell; learned per site). true always renders, false never. |
location |
string | 2-letter country code for the proxy (us, gb, de, …). An unsupported one is refused with the list. |
wait_for |
string | Implies a browser. stable (default), domcontentloaded, networkidle, or a CSS selector to wait for. |
wait_state |
enum | With a selector wait_for: visible (default), nonempty, hidden, stable. |
scroll_steps |
0–10 | Implies a browser. Scroll this many times before the readiness check (lazy content). |
wait_min_ms |
0–10000 | Implies a browser. Minimum delay after navigation. |
settle_ms |
0–25000 | Implies a browser. Ceiling on the settle wait (default 5000) — capture happens as soon as the DOM is quiet for 500 ms. |
wait_rules |
array | Implies a browser. [{if: "#consent", then: "#results"}] — first visible if wins and its then replaces wait_for. |
detect_ms |
0–25000 | Implies a browser. How long to probe wait_rules (default 800). |
max_age |
0–300 | Accept a cached copy this many seconds old. Hits return in ms and carry cached: true. |
template |
string | Parse with a published template (handle/name, or handle/name@3 to pin a version) and return JSON. Forces that template's fetch settings. Find one with find_templates. |
format |
markdown | html |
How the page comes back (default markdown: a fraction of the size). Template results are always JSON. |
select |
string | CSS selector: return only the matching elements, in format. |
fresh |
boolean | Fetch again even if this exact fetch was made in the last 10 minutes. By default that copy is reused — so re-reading it with another select or format costs nothing. |
max_chars |
integer | Cap on returned body (default 120000), after format/select. Longer bodies are cut with a note. |
Responses start with a JSON metadata block (job_id, status, http_response_code,
response_time_ms, render, render_reason, readiness, template_version, location, cached, parse_error, truncated, …),
then notes on what to try next (scroll for more, a narrower select, …), then ---
and the Markdown, HTML or JSON body. API errors (bad key, out of credits,
unknown template, invalid params, concurrency limit) come back as clear tool errors.
Full API reference: https://unblockingapi.com/docs.
Development
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)
Repository layout: src/ (server.ts tools, index.ts stdio entry,
http.ts hosted entry, client.ts API client), Dockerfile (the hosted
image, deployed to mcp.unblockingapi.com by .github/workflows/deploy.yml), .claude-plugin/ (Claude Code
marketplace manifest), plugins/claude/ (the Claude Code plugin: hosted server,
skill, setup command), .cursor-plugin/ and plugins/cursor/ (the Cursor
plugin), docs/ (setup guides).
License
MIT
Perguntas sobre o MCP UnblockingAPI
Como adiciono o MCP UnblockingAPI ao Claude Code?
Execute claude mcp add --env 'UNBLOCKINGAPI_KEY=<YOUR_UNBLOCKINGAPI_KEY>' mcp -- npx -y @unblockingapi/mcp no seu terminal. Adicione --scope user para torná-lo disponível em todos os projetos.
Como adiciono o MCP UnblockingAPI ao Cursor?
Abra ~/.cursor/mcp.json e adicione o servidor em mcpServers, usando a configuração do Cursor mostrada na seção de instalação acima.
Quais ferramentas o MCP UnblockingAPI oferece?
Ele expõe 3 ferramentas, incluindo unblock_fetch, find_templates, get_build_guide.
Como posso obter JSON estruturado de um site?
Você pode usar a ferramenta unblock_fetch com o parâmetro template para transformar uma página em campos nomeados em vez de markup.
Como encontro um template para um site específico?
Use a ferramenta find_templates, que permite pesquisar por URL, palavra-chave ou categoria para encontrar um parser compatível.
O que acontece se um template falhar ao processar um site?
Se um parser falhar porque o site mudou, o servidor retorna o HTML bruto com a flag parse_error: true em vez de um erro.
Preciso instalar algo para usar a versão hospedada?
Não, você pode adicioná-lo como um conector e fazer login via OAuth sem necessidade de instalação.