scrapeunblocker-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScrapeUnblocker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# ScrapeUnblocker MCP server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+Claude (and any other MCP client) fetch **any web page's HTML** through the
+[ScrapeUnblocker](https://scrapeunblocker.com) scraping API, bypassing anti-bot
+protection (Cloudflare, DataDome, PerimeterX, Akamai, Shape).
+
+You bring your **own** API key. Nothing is shared or proxied through us.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `fetch_html` | Fetch the fully rendered HTML of a URL. |
+| `fetch_parsed` | Fetch a page and return AI-parsed structured JSON. |
+| `google_search` | Run a Google search and return organic results as JSON. |
+
+## Get an API key
+
+Sign up and grab your key at **https://app.scrapeunblocker.com**. The server
+reads it from the `SCRAPEUNBLOCKER_KEY` environment variable.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add scrapeunblocker \
+  --env SCRAPEUNBLOCKER_KEY=your_api_key_here \
+  -- npx -y scrapeunblocker-mcp
+```
+
+### Claude Desktop
+
+Add this to your `claude_desktop_config.json`
+(Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "scrapeunblocker": {
+      "command": "npx",
+      "args": ["-y", "scrapeunblocker-mcp"],
+      "env": {
+        "SCRAPEUNBLOCKER_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop and the ScrapeUnblocker tools appear.
+
+### Any other MCP client
+
+Run the server over stdio:
+
+```bash
+SCRAPEUNBLOCKER_KEY=your_api_key_here npx -y scrapeunblocker-mcp
+```
+
+## Example prompts
+
+- "Fetch the HTML of https://www.example-shop.com/product/123 and list the price."
+- "This page keeps blocking me: <url>. Use fetch_html to get it."
+- "Search Google for 'best running shoes 2026' and give me the top 5 links."
+
+## Development
+
+```bash
+npm install
+npm run build      # bundles to dist/ with tsup
+npm run typecheck
+SCRAPEUNBLOCKER_KEY=... node dist/index.js   # run the server
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ScrapeUnblockerClient } from "scrapeunblocker";
+var VERSION = "0.1.0";
+function resolveApiKey() {
+  return process.env.SCRAPEUNBLOCKER_KEY ?? process.env.SCRAPEUNBLOCKER_API_KEY ?? void 0;
+}
+var MISSING_KEY_MESSAGE = "No ScrapeUnblocker API key found. Set the SCRAPEUNBLOCKER_KEY environment variable to your own key (get one at https://app.scrapeunblocker.com) and restart the MCP server.";
+function client() {
+  const apiKey = resolveApiKey();
+  if (!apiKey) throw new Error(MISSING_KEY_MESSAGE);
+  const baseUrl = process.env.SCRAPEUNBLOCKER_BASE_URL || void 0;
+  return new ScrapeUnblockerClient({ apiKey, baseUrl });
+}
+function errorText(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+var server = new McpServer({
+  name: "scrapeunblocker",
+  version: VERSION
+});
+server.registerTool(
+  "fetch_html",
+  {
+    title: "Fetch page HTML",
+    description: "Fetch the fully rendered HTML of any web page through ScrapeUnblocker, bypassing anti-bot protection (Cloudflare, DataDome, PerimeterX, Akamai, Shape). Use this when a normal fetch is blocked (403/429, captcha, 'access denied') or when the page needs a real browser to render. Returns the raw HTML as text.",
+    inputSchema: {
+      url: z.string().url().describe("The absolute URL to fetch (http/https)."),
+      proxy_country: z.string().length(2).optional().describe(
+        "Optional ISO 3166-1 alpha-2 country code to route through, e.g. 'US', 'GB', 'DE'."
+      ),
+      wait_method: z.enum(["css", "js"]).optional().describe(
+        "Optional render-wait strategy: 'css' waits for a selector, 'js' waits for a JS expression to be truthy."
+      ),
+      wait_value: z.string().optional().describe(
+        `The CSS selector or JS expression paired with wait_method (e.g. '#price' or 'document.readyState==="complete"').`
+      ),
+      method_timeout_seconds: z.number().int().positive().optional().describe("Cap in seconds for the render-wait method."),
+      sleep_seconds: z.number().positive().optional().describe("Extra seconds to wait after load before capturing the HTML.")
+    }
+  },
+  async (args) => {
+    try {
+      const html = await client().getPageSource(args.url, {
+        proxyCountry: args.proxy_country,
+        method: args.wait_method,
+        value: args.wait_value,
+        methodTimeout: args.method_timeout_seconds,
+        timeSleep: args.sleep_seconds
+      });
+      return { content: [{ type: "text", text: html }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: errorText(err) }], isError: true };
+    }
+  }
+);
+server.registerTool(
+  "fetch_parsed",
+  {
+    title: "Fetch AI-parsed page data",
+    description: "Fetch a web page through ScrapeUnblocker and return AI-parsed structured JSON instead of raw HTML (e.g. product details, article content). Best for extracting fields from product, listing or article pages without writing your own HTML parsing.",
+    inputSchema: {
+      url: z.string().url().describe("The absolute URL to fetch and parse."),
+      proxy_country: z.string().length(2).optional().describe("Optional ISO country code to route through, e.g. 'US'."),
+      rules_hint: z.string().optional().describe(
+        "Optional natural-language hint about what to extract, to guide parsing."
+      )
+    }
+  },
+  async (args) => {
+    try {
+      const parsed = await client().getParsed(args.url, {
+        proxyCountry: args.proxy_country,
+        rulesHint: args.rules_hint
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }]
+      };
+    } catch (err) {
+      return { content: [{ type: "text", text: errorText(err) }], isError: true };
+    }
+  }
+);
+server.registerTool(
+  "google_search",
+  {
+    title: "Google search results",
+    description: "Run a Google search through ScrapeUnblocker and return the organic results as structured JSON. Use this to discover URLs before fetching them.",
+    inputSchema: {
+      keyword: z.string().min(1).describe("The search query."),
+      proxy_country: z.string().length(2).optional().describe("Optional ISO country code to search from, e.g. 'US'."),
+      pages_to_check: z.number().int().positive().max(10).optional().describe("How many result pages to collect (default 1).")
+    }
+  },
+  async (args) => {
+    try {
+      const results = await client().serp(args.keyword, {
+        proxyCountry: args.proxy_country,
+        pagesToCheck: args.pages_to_check
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+      };
+    } catch (err) {
+      return { content: [{ type: "text", text: errorText(err) }], isError: true };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  if (!resolveApiKey()) {
+    process.stderr.write(
+      "[scrapeunblocker-mcp] Warning: " + MISSING_KEY_MESSAGE + "\n"
+    );
+  }
+}
+main().catch((err) => {
+  process.stderr.write(`[scrapeunblocker-mcp] Fatal: ${errorText(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "scrapeunblocker-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for ScrapeUnblocker - lets Claude fetch any web page's HTML (or AI-parsed JSON) through the ScrapeUnblocker anti-bot API, using your own API key.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "scraping",
+    "web-scraping",
+    "scrapeunblocker",
+    "anti-bot",
+    "cloudflare",
+    "datadome"
+  ],
+  "license": "MIT",
+  "author": "ScrapeUnblocker",
+  "homepage": "https://scrapeunblocker.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ScrapeUnblocker/scrapeunblocker-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ScrapeUnblocker/scrapeunblocker-mcp/issues"
+  },
+  "type": "module",
+  "bin": {
+    "scrapeunblocker-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "scrapeunblocker": "^0.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsup": "^8.0.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.4.0"
+  }
+}