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.

Hosted server

No Node, no install: connect to https://mcp.unblockingapi.com/mcp (Streamable HTTP) and send your key as a header. Same tools, same credits.

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

# VS Code
code --add-mcp '{"name":"unblockingapi","type":"http","url":"https://mcp.unblockingapi.com/mcp","headers":{"Authorization":"Bearer your_api_key_here"}}'

Cursor, Windsurf and other clients that take a URL plus headers:

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

X-Api-Key: your_api_key_here works too. Claude.ai and Claude Desktop custom connectors sign in with OAuth instead of a header, which the hosted server does not offer yet; use the local server there for now. The local server is still the better fit for the Claude Code plugin, which also redirects Claude's built-in web fetch.

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)
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 plugin + marketplace manifests), hooks/, skills/ and commands/ (plugin behaviour), docs/ (setup guides).