@unblockingapi/mcp
OfficialA browser-backed web fetching and structured-data extraction server: fetch bot-protected or JS-heavy pages as Markdown/HTML, and parse supported sites into JSON via templates.
unblock_fetch— fetch any public http(s) URL through rotating residential proxies and a real browser, returning clean Markdown or HTML; handles bot detection, CAPTCHAs, geo-blocks, SPAs and dynamic content (with render/wait/scroll/settle controls,locationproxying, CSSselect, caching viamax_age/fresh, and char caps). 1 credit per success; failures free.unblock_fetchwithtemplate— parse pages on template-covered sites (search engines, marketplaces, real-estate, registries) into named-field JSON instead of markup; supports version pinning (handle/name@3).find_templates— discover templates by URL, keyword, or category, and inspect their output shape (free).get_build_guide— read REST API reference, templates, and recipes (rank tracker, listings aggregator, price monitor) for building apps that call the API (free).Note on schema: the listed
google_searchandidealista_propertytools are stale — removed in 0.4.0 and 0.3.0 respectively; usefind_templates+unblock_fetchinstead. The schema omitsfind_templatesandget_build_guide.Deployment — use the hosted endpoint
https://mcp.unblockingapi.com/mcpwith OAuth or an API key, or run locally vianpx -y @unblockingapi/mcp(stdio,UNBLOCKINGAPI_KEY).
Allows running Google searches and retrieving structured organic results as JSON.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@unblockingapi/mcp Search Google for the latest MCP tools"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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 |
| 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 | 1 credit per success; re-reading the same fetch is free |
| 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 |
| 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 |
|
|
|
|
| none |
| nothing: the guides ship in the package ( | 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 |
| 0.4.0 |
|
| 0.4.0 |
|
| 0.3.0 |
|
| before 0.2.0 (never on npm) |
|
Related MCP server: Spider MCP Server
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/mcpStreamable 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 | |
Cursor | One-click link, or | |
VS Code (Copilot) |
| |
Windsurf |
| |
Lovable | Connectors → + → MCP server, OAuth | |
Replit | Integrations → MCP Servers → + Add MCP server, Test & save | |
Bolt | Connectors → Manage connectors → Custom MCP server, transport HTTP, MCP OAuth | |
Zed |
| |
Cline | Remote Servers tab, | |
Gemini CLI / Antigravity |
| |
Claude API |
| |
n8n | MCP Client Tool, HTTP Streamable, Bearer Auth |
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-pluginsThen 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 |
| yes | — | Your API key. |
| no |
| Override the API base URL. |
| no |
| 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 |
| string, required | http(s) only; media/binary files are rejected. |
| boolean | Omit to let the API decide (plain first, browser when blocked or a JS shell; learned per site). |
| string | 2-letter country code for the proxy ( |
| string | Implies a browser. |
| enum | With a selector |
| 0–10 | Implies a browser. Scroll this many times before the readiness check (lazy content). |
| 0–10000 | Implies a browser. Minimum delay after navigation. |
| 0–25000 | Implies a browser. Ceiling on the settle wait (default 5000) — capture happens as soon as the DOM is quiet for 500 ms. |
| array | Implies a browser. |
| 0–25000 | Implies a browser. How long to probe |
| 0–300 | Accept a cached copy this many seconds old. Hits return in ms and carry |
| string | Parse with a published template ( |
|
| How the page comes back (default |
| string | CSS selector: return only the matching elements, in |
| 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 |
| integer | Cap on returned body (default 120000), after |
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
Available Tools
3 toolsgoogle_searchAInspect
Run a Google search through UnblockingAPI and get structured organic results as JSON. Useful for SERP data, research, and competitive analysis without getting blocked.
Inputs: q (required), uule, start, location.
idealista_propertyAInspect
Extract structured data from an idealista.com property listing (Spain's largest real-estate portal) — price, size, rooms, bathrooms, floor, energy rating, features, photos, advertiser, and more, as JSON. Pass the full listing URL.
Inputs: url (required).
unblock_fetchAInspect
Fetch a URL through UnblockingAPI, bypassing bot detection, CAPTCHAs, and geo-blocks with rotating residential proxies. Returns the page HTML. Set render=true for JavaScript-heavy sites (SPAs, dynamic content) to get the fully rendered DOM.
Inputs: url (required), wait, render, location, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct purpose: unblock_fetch fetches raw HTML, google_search returns structured search results, and idealista_property extracts specific real-estate listing data. There is no overlap or ambiguity between them.
All tool names follow a consistent snake_case pattern and are descriptive, but the pattern isn't strictly verb_noun: unblock_fetch is verb_verb, google_search is noun_verb, and idealista_property is noun_noun. Minor deviation from a uniform convention.
With 3 tools, the set is small but well-scoped for the server's purpose of unblocking web data access. Each tool earns its place, though the count feels slightly thin for broader scraping scenarios.
Generic fetch covers arbitrary URLs, structured search covers SERP data, and a specialized extractor covers a major site. Missing features like custom structured extraction from other sites are workarounds via unblock_fetch, so the surface is reasonably complete for its niche.
Maintenance
Related MCP Connectors
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
Web scraping, search, crawling, structured extraction and research for AI agents.
Fetch any page's HTML or AI-parsed JSON, Google results, or 100+ site plugins via ScrapeUnblocker
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Related MCP Servers
- AlicenseDqualityDmaintenanceEnables AI assistants to reliably fetch web content as markdown and search the web by bypassing bot detection and rendering JavaScript. Provides tools to unblock URLs and search the web with results converted to markdown format.2MIT
- AlicenseAqualityCmaintenanceEnables AI agents to crawl, scrape, search, and automate browsers with anti-bot bypass, providing fast web access via 22 tools.22316 npm3MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with reliable web fetching capabilities, handling retries, caching, and anti-bot bypass automatically.MIT
- AlicenseAqualityBmaintenanceEnables fetching any web page's HTML by bypassing anti-bot protection, and also provides AI-parsed structured data and Google search results.241,377 npm3MIT