@Unblockingapi/

Official Model Context Protocol server and Claude Code plugin for UnblockingAPI. Gives AI agents (Claude, Cursor, VS Code, Zed, …) 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.

Tools

Tool	What it does	Cost
unblock_fetch	Fetch any URL, bypassing anti-bot walls, CAPTCHAs and geo-blocks. Picks plain HTTP or a real browser per site by itself; render forces one. Pass template to get structured JSON instead of HTML.	1 credit per success
find_templates	Find a template that parses a site into JSON — by the URL you are about to fetch, by keyword, or by category.	free

Failed requests are free. The server also ships instructions and a skill so the agent lets the API choose plain fetch or browser per site, and checks for a template before parsing a known site by hand.

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 }

If a parser fails because the site changed, you get raw HTML back with parse_error: true rather than an error.

Setup

You need an UnblockingAPI key — sign up at https://unblockingapi.com (500 free credits, no card).

Detailed guides: Claude (Claude Code plugin, claude mcp add, Claude Desktop) · Cursor · other clients below.

Claude Code — plugin (recommended)

The plugin bundles the MCP server, stores your key, and makes Claude use unblock_fetch instead of its built-in web fetch.

In Claude Code, three lines:

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

The third line matters. Installing does not prompt for your key and succeeds without one, so skipping it leaves every fetch failing. New to this? Run /unblockingapi:setup instead and Claude walks you through it, then checks that it works. From a terminal you can do it in one shot instead, but --config only applies on a fresh install:

claude plugin install unblockingapi@unblockingapi-plugins --config api_key=your_api_key_here

Full walkthrough: docs/claude-setup.md.

Claude Code — plain MCP server

claude mcp add unblockingapi \
  -e UNBLOCKINGAPI_KEY=your_api_key_here \
  -- npx -y @unblockingapi/mcp

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude:

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

Cursor

Add the same block to ~/.cursor/mcp.json (every project) or a project's .cursor/mcp.json. See docs/cursor-setup.md for the one-click install link and a rule that makes the agent prefer unblock_fetch.

VS Code (Copilot agent mode)

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

Install by prompt

Agentic clients that can edit their own config (Claude Code, Cursor's agent, Cline, …) will 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.

ChatGPT and other remote-only clients

ChatGPT connectors need a public HTTPS MCP endpoint. Bridge the stdio server with supergateway and a tunnel:

UNBLOCKINGAPI_KEY=your_api_key_here \
  npx -y supergateway --stdio "npx -y @unblockingapi/mcp" --port 8000
# then e.g. cloudflared tunnel --url http://localhost:8000 → add https://…/sse in ChatGPT

Environment variables

Var	Required	Default	Purpose
UNBLOCKINGAPI_KEY	yes	—	Your API key. (The Claude Code plugin supplies it from its config prompt.)
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.
max_chars	integer	Cap on returned body (default 120000). Longer bodies are truncated 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 ---, then the 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)

Repository layout: src/ (server + API client), .claude-plugin/ (Claude Code plugin + marketplace manifests), hooks/, skills/ and commands/ (plugin behaviour), docs/ (setup guides).

License

MIT