npm - @zenrows/mcp - Versions diffs - 2.0.5 → 2.1.0 - Mend

@zenrows/mcp 2.0.5 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE CHANGED Viewed

@@ -1,6 +1,6 @@
 MIT License
-Copyright (c) 2026 ZenRows
+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

package/README.md CHANGED Viewed

@@ -1,149 +1,94 @@
 <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">
+    <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>
+# Zenrows MCP Server
-<p align="center">
-  <a href="https://www.npmjs.com/package/@zenrows/mcp"><img src="https://img.shields.io/npm/v/@zenrows/mcp" alt="npm version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
-</p>
+The Zenrows MCP (Model Context Protocol) server is the standard way AI systems use Zenrows' web data infrastructure. A single connection gives your AI assistant, agent, or application reliable, real-time access to the live web, including the protected web.
----
-## Quick Start
+[![npm version](https://img.shields.io/npm/v/@zenrows/mcp)](https://www.npmjs.com/package/@zenrows/mcp)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ZenRows/zenrows-mcp/blob/main/LICENSE)
-**Claude Code**
+📚 **Full documentation:** [docs.zenrows.com/mcp/overview](https://docs.zenrows.com/mcp/overview)
-```bash
-claude mcp add zenrows -e ZENROWS_API_KEY=YOUR_API_KEY -- npx -y @zenrows/mcp
-```
+---
-Or ask your AI assistant naturally once configured:
+## Why Zenrows MCP
-```
-Scrape https://example.com and summarize the content.
-```
+- **Reach sites that normally block bots.** Get reliable access to protected sites at scale, without building anti-bot handling yourself.
+- **Managed web data infrastructure.** Proxy rotation, headless browser orchestration, anti-bot handling, and session management run on Zenrows' infrastructure.
+- **Plug into any AI you already use.** Works with any MCP client, including AI assistants, agent frameworks, AI SDKs, IDE plugins, and custom applications.
+- **Plain English, no scraping code.** Describe the task naturally and the AI picks the right tool. No selectors, no proxy management, no anti-bot tuning.
 ---
-## 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`                                                                                                                  |
+## Quick start
----
+Zenrows MCP supports two transport options. Both expose the same set of tools and capabilities. Pick the one that fits your client.
-## When to use which options
+### Remote MCP server
-**Content doesn't appear or page is blank**
-→ Enable `js_render: true`. The page likely uses React, Vue, or Angular.
+Use the hosted Zenrows MCP server when your AI application calls an LLM API directly. The server runs on Zenrows' infrastructure, so there is nothing to install, configure, or update.
-**Getting 403 or blocked errors**
-→ Add `premium_proxy: true`. For geo-restricted content, also set `proxy_country`.
+**Server URL:**
-**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`.
+```
+https://mcp.zenrows.com/mcp
+```
-**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.
+**Transport:** Streamable HTTP
-**Need to verify what the page looks like**
-→ Use `screenshot` or `screenshot_fullpage` for visual debugging.
-→ Use `screenshot_selector` to capture a specific element.
+**Authentication:** OAuth-based. Pass your Zenrows API key as a Bearer token in the `Authorization` header on every request.
----
+```
+Authorization: Bearer YOUR_ZENROWS_API_KEY
+```
-## Installation
+Most MCP clients accept this through an `authorization` shorthand field on the tool config and forward it as the Bearer token automatically. Some clients use a free-form `headers` field instead. Either approach works.
-### Claude Desktop
+#### Example: OpenAI Responses API
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```python
+import os
+from openai import OpenAI
-```json
-{
-  "mcpServers": {
-    "zenrows": {
-      "command": "npx",
-      "args": ["-y", "@zenrows/mcp"],
-      "env": {
-        "ZENROWS_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
+ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
+client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
-### Claude Code
+response = client.responses.create(
+    model="gpt-5",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "zenrows",
+            "server_description": "Web scraping MCP server for accessing live web content.",
+            "server_url": "https://mcp.zenrows.com/mcp",
+            "authorization": ZENROWS_API_KEY,
+            "require_approval": "never",
+        }
+    ],
+    input="Visit https://news.ycombinator.com/ and summarize the three most recent posts.",
+)
-```bash
-claude mcp add zenrows -e ZENROWS_API_KEY=YOUR_API_KEY -- npx -y @zenrows/mcp
+print(response.output_text)
 ```
-Or add to your project's `.mcp.json`:
+For the full walkthrough with framework-specific examples, see the [Remote MCP server docs](https://docs.zenrows.com/mcp/overview#remote-mcp-server).
-```json
-{
-  "mcpServers": {
-    "zenrows": {
-      "command": "npx",
-      "args": ["-y", "@zenrows/mcp"],
-      "env": {
-        "ZENROWS_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
+### Local MCP server
-### Cursor
+Use the local stdio configuration when your MCP client runs the server as a local subprocess instead of calling a remote URL. This is the standard setup for desktop AI tools and IDE plugins, including Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Zed, and JetBrains IDEs.
-Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+**Package:** [`@zenrows/mcp`](https://www.npmjs.com/package/@zenrows/mcp) on npm
-```json
-{
-  "mcpServers": {
-    "zenrows": {
-      "command": "npx",
-      "args": ["-y", "@zenrows/mcp"],
-      "env": {
-        "ZENROWS_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
+**Authentication:** API key via the `ZENROWS_API_KEY` environment variable.
-### Windsurf
+**Requirements:** [Node.js](https://nodejs.org/) installed (for `npx` to work).
-Edit `~/.codeium/windsurf/mcp_config.json`:
+**Configuration:**
 ```json
 {
@@ -152,98 +97,56 @@ Edit `~/.codeium/windsurf/mcp_config.json`:
       "command": "npx",
       "args": ["-y", "@zenrows/mcp"],
       "env": {
-        "ZENROWS_API_KEY": "YOUR_API_KEY"
+        "ZENROWS_API_KEY": "YOUR_ZENROWS_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"
-      }
-    }
-  }
-}
-```
+The exact location of this config varies by client. See the [per-client setup guides](https://docs.zenrows.com/mcp/overview#per-client-setup-guides) for the file path for your client.
-### Zed
+---
-Edit `~/.config/zed/settings.json`:
+## Tools
-```json
-{
-  "context_servers": {
-    "zenrows": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "@zenrows/mcp"],
-        "env": {
-          "ZENROWS_API_KEY": "YOUR_API_KEY"
-        }
-      }
-    }
-  }
-}
-```
+The Zenrows MCP exposes two families of tools:
-### JetBrains IDEs
+- **`scrape`**: single-request fetch returning Markdown, plain text, HTML, JSON, PDF, or screenshot. Backed by [Fetch](https://docs.zenrows.com/fetch/api-reference).
+- **`browser_*`**: 30+ tools for full browser automation including navigation, clicks, form fills, JavaScript execution, cookies, tabs, and persistent sessions. Backed by [Browser Sessions](https://docs.zenrows.com/browser-sessions/introduction).
-Go to **Settings → Tools → AI Assistant → Model Context Protocol** and add:
+The AI selects the right tool from your prompt. You don't call tools directly in code.
-```json
-{
-  "mcpServers": {
-    "zenrows": {
-      "command": "npx",
-      "args": ["-y", "@zenrows/mcp"],
-      "env": {
-        "ZENROWS_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
+See the [full tool reference](https://docs.zenrows.com/mcp/overview#tools) for every tool, parameter, and return value.
 ---
-## Examples
-Once configured, ask your AI assistant naturally:
+## 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.js 20.6+)
+npm run build          # Compile to dist/
+npm run inspect        # Open the MCP inspector UI
 ```
-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.
+Pull requests and issues are welcome.
-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.
+## Resources
-Scrape https://protected-site.com — it keeps blocking me, use premium proxies.
-```
+- [Full Zenrows MCP documentation](https://docs.zenrows.com/mcp/overview)
+- [Zenrows Fetch](https://docs.zenrows.com/fetch/api-reference)
+- [Zenrows Browser Sessions](https://docs.zenrows.com/browser-sessions/introduction)
+- [npm package](https://www.npmjs.com/package/@zenrows/mcp)
+- [Get your API key](https://app.zenrows.com/register)
 ---
-## Development
+## License
-```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
-```
+[MIT](LICENSE)

package/dist/http.js CHANGED Viewed

@@ -5,9 +5,6 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { createServer } from "./server.js";
 // ─── app ──────────────────────────────────────────────────────────────────────
 const app = new Hono();
-// Cache MCP client name per API key across invocations.
-// Populated from the clientInfo field in MCP initialize requests.
-const mcpClientCache = new Map();
 // CORS — required for browser-side MCP clients (Claude.ai, Cursor web, etc.)
 // All origins allowed: the API key is the auth mechanism, not the origin.
 app.use(cors({
@@ -50,9 +47,58 @@ app.get("/.well-known/oauth-authorization-server", (c) => c.json({
     code_challenge_methods_supported: ["S256"],
     token_endpoint_auth_methods_supported: ["none"],
 }));
+// MCP Server Card (SEP-2127 canonical + SEP-1649 legacy paths).
+// Lets agents discover this remote MCP before connecting.
+function mcpServerCard() {
+    return {
+        $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+        name: "io.zenrows/mcp",
+        version: "2.0.6",
+        description: "ZenRows MCP — scrape and extract from protected sites via the Universal Scraper API (anti-bot bypass, JS rendering, proxies).",
+        websiteUrl: "https://www.zenrows.com/mcp",
+        remotes: [
+            {
+                type: "streamable-http",
+                url: `${MCP_SERVER}/mcp`,
+                headers: {
+                    Authorization: "Bearer ${ZENROWS_API_KEY}",
+                },
+            },
+        ],
+        // Older SEP-1649-shaped fields some scanners still expect.
+        protocolVersion: "2025-06-18",
+        serverInfo: {
+            name: "ZenRows",
+            version: "2.0.6",
+            description: "ZenRows Universal Scraper API via MCP",
+            homepage: "https://www.zenrows.com/mcp",
+        },
+        transport: {
+            type: "streamable-http",
+            url: `${MCP_SERVER}/mcp`,
+        },
+        capabilities: {
+            tools: true,
+            resources: false,
+            prompts: false,
+        },
+    };
+}
+app.get("/.well-known/mcp.json", (c) => c.json(mcpServerCard(), 200, {
+    "Cache-Control": "public, max-age=300",
+    "X-Content-Type-Options": "nosniff",
+}));
+app.get("/.well-known/mcp/server-card.json", (c) => c.json(mcpServerCard(), 200, {
+    "Cache-Control": "public, max-age=300",
+    "X-Content-Type-Options": "nosniff",
+}));
+app.get("/.well-known/mcp/server-cards.json", (c) => c.json(mcpServerCard(), 200, {
+    "Cache-Control": "public, max-age=300",
+    "X-Content-Type-Options": "nosniff",
+}));
 // RFC 7591 — Dynamic Client Registration
 // MCP clients (Claude.ai, Cursor, etc.) register themselves before initiating OAuth.
-// Since ZenRows API keys are the real auth mechanism, client registration is stateless —
+// Since Zenrows API keys are the real auth mechanism, client registration is stateless —
 // we echo back a stable client_id derived from the request (or the one the client provides).
 app.post("/register", async (c) => {
     const body = await c.req.json().catch(() => ({}));
@@ -96,17 +142,9 @@ app.all("/mcp", async (c) => {
         sessionIdGenerator: undefined, // stateless — no session tracking between requests
         enableJsonResponse: true, // return JSON instead of SSE (simpler for Lambda + most MCP clients)
     });
-    // Use cached client name from a prior initialize request (stateless transport
-    // creates a new server per request, so getClientVersion() is only set during
-    // the initialize request itself, not during subsequent tool calls).
-    const server = createServer(apiKey, mcpClientCache.get(apiKey));
+    const server = createServer(apiKey, c.req.raw.headers.get("user-agent") ?? undefined);
     await server.connect(transport);
     const response = await transport.handleRequest(c.req.raw);
-    // If this was an initialize request, getClientVersion() is now set — cache it
-    // so subsequent tool call requests can include x-mcp-client-name.
-    const resolvedName = server.server.getClientVersion()?.name;
-    if (resolvedName)
-        mcpClientCache.set(apiKey, resolvedName);
     await transport.close();
     return response;
 });
@@ -136,6 +174,6 @@ export const handler = async (event) => {
 if (!process.env.AWS_LAMBDA_FUNCTION_NAME) {
     const port = Number(process.env.PORT) || 3000;
     serve({ fetch: app.fetch, port }, () => {
-        process.stderr.write(`ZenRows MCP HTTP server listening on http://localhost:${port}/mcp\n`);
+        process.stderr.write(`Zenrows MCP HTTP server listening on http://localhost:${port}/mcp\n`);
     });
 }

package/dist/index.js CHANGED Viewed

@@ -9,4 +9,4 @@ if (!apiKey) {
 const server = createServer(apiKey);
 const transport = new StdioServerTransport();
 await server.connect(transport);
-process.stderr.write("ZenRows MCP server running on stdio\n");
+process.stderr.write("Zenrows MCP server running on stdio\n");

package/dist/server.js CHANGED Viewed

@@ -23,7 +23,7 @@ export function createServer(apiKey, clientName) {
             readOnlyHint: true,
             destructiveHint: false,
         },
-        description: `Scrape any webpage and return its content using ZenRows.
+        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.
@@ -67,7 +67,7 @@ Examples:
                 .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). " +
+                "'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()
@@ -154,7 +154,7 @@ Examples:
         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.
+        // '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 ?? DEFAULT_RESPONSE_TYPE;
         if (!params.autoparse &&
@@ -179,7 +179,7 @@ Examples:
                 content: [
                     {
                         type: "text",
-                        text: `Network error contacting ZenRows: ${err instanceof Error ? err.message : String(err)}`,
+                        text: `Network error contacting Zenrows: ${err instanceof Error ? err.message : String(err)}`,
                     },
                 ],
                 isError: true,
@@ -188,7 +188,7 @@ Examples:
         if (!response.ok) {
             const body = await response.text();
             return {
-                content: [{ type: "text", text: `ZenRows error ${response.status}: ${body}` }],
+                content: [{ type: "text", text: `Zenrows error ${response.status}: ${body}` }],
                 isError: true,
             };
         }
@@ -225,7 +225,7 @@ Examples:
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Scrape ${url} using the ZenRows MCP scrape tool and provide a concise summary of the main content. Include key points, headings, and any important data found on the page.`,
+                    text: `Scrape ${url} using the Zenrows MCP scrape tool and provide a concise summary of the main content. Include key points, headings, and any important data found on the page.`,
                 },
             },
         ],
@@ -245,7 +245,7 @@ Examples:
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Scrape ${url} using the ZenRows MCP scrape tool with css_extractor set to ${fields}. Return the extracted data as a clean JSON object.`,
+                    text: `Scrape ${url} using the Zenrows MCP scrape tool with css_extractor set to ${fields}. Return the extracted data as a clean JSON object.`,
                 },
             },
         ],
@@ -262,7 +262,7 @@ Examples:
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Scrape ${url} using the ZenRows MCP scrape tool with js_render set to true. The page requires JavaScript execution to load its content. Return the full rendered content in markdown format.`,
+                    text: `Scrape ${url} using the Zenrows MCP scrape tool with js_render set to true. The page requires JavaScript execution to load its content. Return the full rendered content in markdown format.`,
                 },
             },
         ],

package/dist/tools/browser.js CHANGED Viewed

@@ -15,10 +15,10 @@ export function registerBrowserTools(server, apiKey, browserUrl, getClientName)
     // ─── Session ─────────────────────────────────────────────────────────────
     server.registerTool("browser_navigate", {
         annotations: { title: "Open Browser & Navigate", readOnlyHint: false, destructiveHint: false },
-        description: `Open a ZenRows Scraping Browser session and navigate to a URL.
+        description: `Open a Zenrows Browser Sessions session and navigate to a URL.
 This is the entry point for all browser automation. It creates a new session backed by
-ZenRows' anti-bot infrastructure and navigates to the given URL in one step.
+Zenrows' anti-bot infrastructure and navigates to the given URL in one step.
 Returns a session_id that must be passed to every subsequent browser_* tool call.
 Always call browser_close when done to close the session and free resources.

package/package.json CHANGED Viewed

@@ -1,10 +1,10 @@
 {
   "name": "@zenrows/mcp",
-  "version": "2.0.5",
-  "description": "ZenRows MCP server — Universal Scraper API for AI coding assistants",
+  "version": "2.1.0",
+  "description": "Zenrows MCP server — Fetch and Browser Sessions for AI coding assistants",
   "type": "module",
   "bin": {
-    "zenrows-mcp": "./dist/index.js"
+    "zenrows-mcp": "dist/index.js"
   },
   "files": [
     "dist"
@@ -55,6 +55,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ZenRows/zenrows-mcp"
+    "url": "git+https://github.com/ZenRows/zenrows-mcp.git"
   }
 }