@zenrows/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZenRows
+
+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,248 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/zenrows_light.svg">
+    <img src="assets/zenrows_dark.svg" alt="ZenRows MCP" width="380">
+  </picture>
+</p>
+
+<p align="center">
+  Model Context Protocol server for the <a href="https://www.zenrows.com/products/universal-scraper">ZenRows Universal Scraper API</a>.<br>
+  Give any MCP-compatible AI assistant the ability to scrape any webpage — including JavaScript-rendered content and anti-bot protected sites.
+</p>
+
+---
+
+## Quick Start
+
+**Claude Code**
+```bash
+claude mcp add zenrows -e ZENROWS_API_KEY=YOUR_API_KEY -- npx -y @zenrows/mcp
+```
+
+Or ask your AI assistant naturally once configured:
+```
+Scrape https://example.com and summarize the content.
+```
+
+---
+
+## Tool
+
+### `scrape`
+
+Fetches a webpage and returns its content as clean markdown (default), plaintext, raw HTML, PDF, structured JSON, or a screenshot. See the [ZenRows API docs](https://docs.zenrows.com/universal-scraper-api/api-reference#parameter-overview) for full parameter reference.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | string | **required** | Webpage URL to scrape |
+| `js_render` | boolean | `false` | Enable JS rendering for SPAs and dynamic content |
+| `premium_proxy` | boolean | `false` | Use residential proxies to bypass anti-bot systems |
+| `proxy_country` | string | — | ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`). Requires `premium_proxy` |
+| `response_type` | `markdown` \| `plaintext` \| `pdf` \| `html` | `markdown` | Output format. `html` returns raw source (ZenRows default when no param is sent). Ignored when `autoparse`, `css_extractor`, `outputs`, or screenshot params are set |
+| `autoparse` | boolean | — | Auto-extract structured JSON from the page |
+| `css_extractor` | string | — | JSON map of CSS selectors: `{"title":"h1","price":".price"}` |
+| `outputs` | string | — | Comma-separated data types to extract as JSON: `emails`, `headings`, `links`, `menus`, `images`, `videos`, `audios`. Use `*` for all |
+| `screenshot` | boolean | — | Capture an above-the-fold screenshot. Returns an image |
+| `screenshot_fullpage` | boolean | — | Capture a full-page screenshot. Returns an image |
+| `screenshot_selector` | string | — | Capture a screenshot of a specific element via CSS selector |
+| `wait_for` | string | — | CSS selector to wait for before capturing. Requires `js_render` |
+| `wait` | number | — | Milliseconds to wait after load (max 30000). Requires `js_render` |
+| `js_instructions` | string | — | JSON array of browser actions. Requires `js_render` |
+
+---
+
+## When to use which options
+
+**Content doesn't appear or page is blank**
+→ Enable `js_render: true`. The page likely uses React, Vue, or Angular.
+
+**Getting 403 or blocked errors**
+→ Add `premium_proxy: true`. For geo-restricted content, also set `proxy_country`.
+
+**Content loads after a delay or interaction**
+→ Use `wait_for` (CSS selector) or `wait` (milliseconds) with `js_render: true`.
+→ For clicks or form inputs before scraping, use `js_instructions`.
+
+**Only need specific data, not the full page**
+→ Use `css_extractor` with a JSON map of selectors for precise extraction.
+→ Use `autoparse` for structured pages like products or articles.
+→ Use `outputs` to pull links, emails, images, or other content types.
+
+**Need to verify what the page looks like**
+→ Use `screenshot` or `screenshot_fullpage` for visual debugging.
+→ Use `screenshot_selector` to capture a specific element.
+
+---
+
+## Installation
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add zenrows -e ZENROWS_API_KEY=YOUR_API_KEY -- npx -y @zenrows/mcp
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+Edit `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "zenrows": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Zed
+
+Edit `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "zenrows": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@zenrows/mcp"],
+        "env": {
+          "ZENROWS_API_KEY": "YOUR_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+### JetBrains IDEs
+
+Go to **Settings → Tools → AI Assistant → Model Context Protocol** and add:
+
+```json
+{
+  "mcpServers": {
+    "zenrows": {
+      "command": "npx",
+      "args": ["-y", "@zenrows/mcp"],
+      "env": {
+        "ZENROWS_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+Once configured, ask your AI assistant naturally:
+
+```
+Scrape the pricing page at https://zenrows.com/pricing and summarize the plans.
+
+Fetch https://example.com/ — it's a React SPA, so enable JS rendering.
+
+Get the top 5 results from https://www.scrapingcourse.com/ecommerce/ and extract just the product names and prices.
+
+Take a full-page screenshot of https://news.ycombinator.com to see the current layout.
+
+Scrape https://protected-site.com — it keeps blocking me, use premium proxies.
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ZenRows/zenrows-mcp
+cd zenrows-mcp
+npm install
+cp .env.example .env   # add your API key
+npm run dev            # run with .env loaded (requires Node 20.6+)
+npm run build          # compile to dist/
+npm run inspect        # open MCP inspector UI
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { createRequire } from "module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const ZENROWS_API_URL = "https://api.zenrows.com/v1/";
+const apiKey = process.env.ZENROWS_API_KEY;
+if (!apiKey) {
+    process.stderr.write("Error: ZENROWS_API_KEY environment variable is required\n");
+    process.exit(1);
+}
+const server = new McpServer({
+    name: "zenrows",
+    version: pkg.version,
+});
+// ─── scrape ──────────────────────────────────────────────────────────────────
+server.registerTool("scrape", {
+    description: `Scrape any webpage and return its content using ZenRows.
+
+Use this tool to fetch webpage content for analysis. By default it returns clean
+markdown, which is ideal for LLM processing.
+
+When to enable options:
+- js_render: page uses React/Vue/Angular, loads content dynamically, or content
+  appears missing on the first attempt
+- premium_proxy: site returns 403/blocked errors even with js_render enabled
+- wait_for: specific content loads after initial render (requires js_render)
+- css_extractor: you only need specific elements, not the whole page
+- autoparse: structured data pages like products or articles
+
+Examples:
+  Basic:    { url: "https://example.com" }
+  Dynamic:  { url: "https://spa.com", js_render: true }
+  Protected:{ url: "https://protected.com", js_render: true, premium_proxy: true }
+  Extract:  { url: "https://shop.com", css_extractor: '{"title":"h1","price":".price"}' }`,
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .describe("The webpage URL to scrape"),
+        js_render: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Enable JavaScript rendering via headless browser. Required for SPAs " +
+            "(React, Vue, Angular) and pages that load content dynamically."),
+        premium_proxy: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Use premium residential proxies to bypass anti-bot protection. " +
+            "Required for heavily protected sites. Implies higher credit cost."),
+        proxy_country: z
+            .string()
+            .optional()
+            .describe("Country for geo-targeted scraping. ISO 3166-1 alpha-2 code (e.g. 'US', 'GB', 'DE'). " +
+            "Requires premium_proxy=true."),
+        response_type: z
+            .enum(["markdown", "plaintext", "pdf", "html"])
+            .optional()
+            .default("markdown")
+            .describe("Output format. 'markdown' (default) preserves structure and is ideal for LLMs. " +
+            "'plaintext' strips all formatting for pure text extraction. " +
+            "'pdf' returns a PDF of the page. " +
+            "'html' returns the raw HTML source (omits the response_type param; ZenRows default). " +
+            "Ignored when autoparse, css_extractor, outputs, or screenshot params are set."),
+        autoparse: z
+            .boolean()
+            .optional()
+            .describe("Automatically extract structured data from the page into JSON. " +
+            "Best for product pages, articles, and listings."),
+        css_extractor: z
+            .string()
+            .optional()
+            .describe("Extract specific elements using CSS selectors. " +
+            'JSON object mapping names to selectors, e.g. \'{"title":"h1","price":".price-tag"}\'. ' +
+            "Returns JSON instead of full page content."),
+        wait_for: z
+            .string()
+            .optional()
+            .describe("CSS selector to wait for before capturing. Use when key content loads " +
+            "after the initial page render. Requires js_render=true."),
+        wait: z
+            .number()
+            .int()
+            .min(0)
+            .max(30000)
+            .optional()
+            .describe("Milliseconds to wait after page load before capturing content. " +
+            "Max 30000 (30s). Requires js_render=true."),
+        js_instructions: z
+            .string()
+            .optional()
+            .describe("JSON array of browser interactions to run before scraping. Requires js_render=true. " +
+            'Example: [{"click":"#load-more"},{"wait":1000},{"wait_for":".results"}]'),
+        outputs: z
+            .string()
+            .optional()
+            .describe("Comma-separated list of data types to extract as structured JSON. " +
+            "Available: emails, headings, links, menus, images, videos, audios. " +
+            "Use '*' for all types. Returns JSON instead of full page content."),
+        screenshot: z
+            .boolean()
+            .optional()
+            .describe("Capture an above-the-fold screenshot of the page. " +
+            "Returns an image instead of text content. Useful for visual verification or debugging."),
+        screenshot_fullpage: z
+            .boolean()
+            .optional()
+            .describe("Capture a full-page screenshot including content below the fold. " +
+            "Returns an image instead of text content."),
+        screenshot_selector: z
+            .string()
+            .optional()
+            .describe("Capture a screenshot of a specific element using a CSS selector. " +
+            'Example: ".product-card". Returns an image instead of text content.'),
+    },
+}, async (params) => {
+    const searchParams = new URLSearchParams({
+        apikey: apiKey,
+        url: params.url,
+    });
+    if (params.js_render || params.screenshot || params.screenshot_fullpage || params.screenshot_selector)
+        searchParams.set("js_render", "true");
+    if (params.premium_proxy)
+        searchParams.set("premium_proxy", "true");
+    if (params.proxy_country)
+        searchParams.set("proxy_country", params.proxy_country.toUpperCase());
+    if (params.autoparse)
+        searchParams.set("autoparse", "true");
+    if (params.css_extractor)
+        searchParams.set("css_extractor", params.css_extractor);
+    if (params.wait_for)
+        searchParams.set("wait_for", params.wait_for);
+    if (params.wait != null)
+        searchParams.set("wait", String(params.wait));
+    if (params.js_instructions)
+        searchParams.set("js_instructions", params.js_instructions);
+    if (params.outputs)
+        searchParams.set("outputs", params.outputs);
+    if (params.screenshot || params.screenshot_fullpage || params.screenshot_selector)
+        searchParams.set("screenshot", "true");
+    if (params.screenshot_fullpage)
+        searchParams.set("screenshot_fullpage", "true");
+    if (params.screenshot_selector)
+        searchParams.set("screenshot_selector", params.screenshot_selector);
+    // response_type is mutually exclusive with autoparse, css_extractor, outputs, and screenshot params.
+    // 'html' is the ZenRows default (no param); all other values are passed through.
+    const isScreenshot = params.screenshot || params.screenshot_fullpage || params.screenshot_selector;
+    const effectiveType = params.response_type ?? "markdown";
+    if (!params.autoparse && !params.css_extractor && !params.outputs && !isScreenshot && effectiveType !== "html") {
+        searchParams.set("response_type", effectiveType);
+    }
+    let response;
+    try {
+        response = await fetch(`${ZENROWS_API_URL}?${searchParams}`, {
+            headers: { "User-Agent": `zenrows/mcp ${pkg.version}` },
+        });
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Network error contacting ZenRows: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (!response.ok) {
+        const body = await response.text();
+        return {
+            content: [{ type: "text", text: `ZenRows error ${response.status}: ${body}` }],
+            isError: true,
+        };
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const buffer = await response.arrayBuffer();
+    const bytes = new Uint8Array(buffer);
+    const isPng = bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47;
+    const isJpeg = bytes[0] === 0xff && bytes[1] === 0xd8;
+    if (contentType.startsWith("image/") || isPng || isJpeg) {
+        const mimeType = isPng ? "image/png" : isJpeg ? "image/jpeg" : contentType.split(";")[0].trim();
+        const base64 = Buffer.from(buffer).toString("base64");
+        return {
+            content: [{ type: "image", data: base64, mimeType }],
+        };
+    }
+    return {
+        content: [{ type: "text", text: new TextDecoder().decode(buffer) }],
+    };
+});
+// ─── boot ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("ZenRows MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zenrows/mcp",
+  "version": "1.0.0",
+  "description": "ZenRows MCP server — Universal Scraper API for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "zenrows-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "node --env-file=.env --import tsx src/index.ts",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "keywords": [
+    "mcp",
+    "zenrows",
+    "scraping",
+    "web-scraping",
+    "model-context-protocol",
+    "ai",
+    "llm"
+  ],
+  "mcpName": "io.github.ZenRows/zenrows-mcp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZenRows/zenrows-mcp"
+  }
+}