Mcp MCP Server

@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

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

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:

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>).

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

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

# Claude Code
claude mcp add unblockingapi -e UNBLOCKINGAPI_KEY=your_api_key_here -- npx -y @unblockingapi/mcp

# VS Code
code --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:

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

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

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