UnblockingAPI

io.github.unblockingapiPublished by GitHub account unblockingapiv0.8.2Updated Oct 30, 2026

Fetch bot-protected and JavaScript-heavy pages for AI agents, or parse them to JSON with templates.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingBrowser Automation

Overview

AI-generated overview

UnblockingAPI fetches bot-protected and JavaScript-heavy web pages through a real browser and residential proxies, returning Markdown, HTML or template-based…

What you can do
  • Fetch pages that block simple requests or need JavaScript, with options for country, scrolling, waiting and CSS selection
  • Find published templates that parse a site into structured JSON, by URL, keyword or category
  • Read build guides for calling the underlying REST API from your own app or script
  • Return page content as Markdown, cleaned HTML or JSON, with metadata on how it was rendered
When to use it
Useful when an assistant needs to read pages that a plain HTTP fetch cannot handle: JavaScript-rendered sites, bot walls, geo-specific content, or well-known sites that already have a parsing template.
Requirements
Either the hosted endpoint with OAuth sign-in, or the local npm package over stdio with Node.js 18+. An UnblockingAPI account is required; the local server needs the key in UNBLOCKINGAPI_KEY, and clients without sign-in send it as an Authorization bearer header. Network access to the UnblockingAPI API.
Before you install
Fetches consume paid credits: each successful fetch costs 1 credit, while failures and re-reads of the same fetch within 10 minutes are free. The API key is a secret; keep it server-side and prefer OAuth sign-in where available. Requested URLs and options are sent to UnblockingAPI's servers and routed through third-party residential proxies.

Installation

In SourceWeft

  1. Open UnblockingAPI in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.unblockingapi%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "unblockingapi": {
      "type": "http",
      "url": "https://mcp.unblockingapi.com/mcp"
    }
  }
}

README

@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

ToolWhat it doesCost
unblock_fetchFetch 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_templatesFind 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_guideGuides 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-searchunblock_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

ToolCallsKey
unblock_fetchPOST https://api.unblockingapi.com/unblock (JSON body; template selects a template)X-Api-Key
find_templatesGET 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 matchnone
get_build_guidenothing: 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 toolRemoved inUse instead
google_search0.4.0find_templates(url: "https://www.google.com/search?q=…"), then unblock_fetch(url, template: "kjellberg/google-search")
list_templates0.4.0find_templates (now also takes url)
idealista_property0.3.0find_templates(url) for the Idealista page, then unblock_fetch with the template it returns
ahrefs_website_authoritybefore 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:

  1. Hosted server — paste one URL into your app and sign in. Nothing to install, no key to copy. Recommended for most apps.
  2. Claude Code plugin — the hosted server plus a skill and a setup command, signed in with your account.
  3. 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>).

AppHowGuide
Claude.ai, Claude DesktopCustomize → Connectors → + Add → Add custom connector, paste the URL, Connectunblockingapi.com/tools/claude
CursorOne-click link, or "url" in ~/.cursor/mcp.json, then Login under Settings → MCPdocs/cursor-setup.md · site
VS Code (Copilot)code --add-mcp '{"name":"unblockingapi","type":"http","url":"https://mcp.unblockingapi.com/mcp"}', sign in on first usesite
Windsurf"serverUrl" in the MCP config (Cascade → MCPs → Open MCP config file)site
LovableConnectors → + → MCP server, OAuthsite
ReplitIntegrations → MCP Servers → + Add MCP server, Test & savesite
BoltConnectors → Manage connectors → Custom MCP server, transport HTTP, MCP OAuthsite
Zed"url" (+ "headers") under context_serverssite
ClineRemote Servers tab, "type": "streamableHttp" + key headersite
Gemini CLI / Antigravitygemini mcp add --transport http … / "serverUrl" + key headersite
Claude APImcp_servers entry, your key as authorization_tokensite
n8nMCP Client Tool, HTTP Streamable, Bearer Authsite

With a key instead of signing in:

bash
# Claude Codeclaude mcp add --transport http unblockingapi https://mcp.unblockingapi.com/mcp \  --header "Authorization: Bearer your_api_key_here"
json
{  "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

The same server over stdio. Needs Node.js 18+ and your key in UNBLOCKINGAPI_KEY.

bash
# Claude Codeclaude mcp add unblockingapi -e UNBLOCKINGAPI_KEY=your_api_key_here -- npx -y @unblockingapi/mcp
# VS Codecode --add-mcp '{"name":"unblockingapi","command":"npx","args":["-y","@unblockingapi/mcp"],"env":{"UNBLOCKINGAPI_KEY":"your_api_key_here"}}'

Claude Desktop (claude_desktop_config.json; restart after editing), Cursor (~/.cursor/mcp.json) and most other apps take this block:

json
{  "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)

VarRequiredDefaultPurpose
UNBLOCKINGAPI_KEYyes—Your API key.
UNBLOCKINGAPI_BASE_URLnohttps://api.unblockingapi.comOverride the API base URL.
UNBLOCKINGAPI_TIMEOUT_MSno180000Per-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

ParamTypeNotes
urlstring, requiredhttp(s) only; media/binary files are rejected.
renderbooleanOmit to let the API decide (plain first, browser when blocked or a JS shell; learned per site). true always renders, false never.
locationstring2-letter country code for the proxy (us, gb, de, …). An unsupported one is refused with the list.
wait_forstringImplies a browser. stable (default), domcontentloaded, networkidle, or a CSS selector to wait for.
wait_stateenumWith a selector wait_for: visible (default), nonempty, hidden, stable.
scroll_steps0–10Implies a browser. Scroll this many times before the readiness check (lazy content).
wait_min_ms0–10000Implies a browser. Minimum delay after navigation.
settle_ms0–25000Implies a browser. Ceiling on the settle wait (default 5000) — capture happens as soon as the DOM is quiet for 500 ms.
wait_rulesarrayImplies a browser. [{if: "#consent", then: "#results"}] — first visible if wins and its then replaces wait_for.
detect_ms0–25000Implies a browser. How long to probe wait_rules (default 800).
max_age0–300Accept a cached copy this many seconds old. Hits return in ms and carry cached: true.
templatestringParse 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.
formatmarkdown | htmlHow the page comes back (default markdown: a fraction of the size). Template results are always JSON.
selectstringCSS selector: return only the matching elements, in format.
freshbooleanFetch 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_charsintegerCap 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

bash
npm installnpm run dev        # tsx watchnpm run typecheck  # tsc --noEmitnpm 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

[@unblockingapi/mcp MCP server – quality and maintenance score on Glama]

[@unblockingapi/mcp MCP server – quality and maintenance score on Glama]

Source: README.md at commit 973be89

Tools

3

unblock_fetch

Fetch a URL through UnblockingAPI

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.

Parametersurlrequiredfreshformatrenderselectmax_agelocationtemplatewait_fordetect_msmax_charssettle_ms+4 more

find_templates

Find a structured-data template

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.

Parametersurlpagelimitsearchcategory

get_build_guide

How to build an app on UnblockingAPI

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.

Parameterstopicrequired

Version history

4
  1. v0.8.2LatestOct 22, 2026
  2. v0.8.1Oct 20, 2026
  3. v0.8.0Oct 20, 2026
  4. v0.6.0Oct 19, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts