Browser MCP Server

An MCP (Model Context Protocol) server that gives AI agents a real, anti-bot-aware browser via Zyte API — navigate pages, click/type/scroll, take screenshots, and extract structured data, with automatic proxy/IP rotation and ban avoidance.

Built with NestJS and @nestjs-mcp/server, talking to Zyte's /extract endpoint directly over HTTP. Transport is streamable HTTP only, served stateless at a single /mcp endpoint.

Setup

1. Copy .env.example to .env and fill in:

   Variable	Required	Description
   ZYTE_API_KEY	yes	Your Zyte API key
   ZYTE_API_BASE_URL	no	Override the Zyte API base URL (default https://api.zyte.com/v1)
   PORT	no	HTTP port (default 3000)
   BROWSER_TIMEOUT_MS	no	Per-request timeout for calls to Zyte (default 30000)
   BROWSER_MAX_RETRIES	no	Retries for rate-limit (429/503) and temporary ban (520) responses, with exponential backoff (default 2)

2. Install dependencies and start the server:

   pnpm install
   pnpm run start:dev
   

   The MCP endpoint is served at http://localhost:3000/mcp.

Tools

Tool	Returns
browser_browse	Opens a URL, optionally runs actions (click/type/select/scroll/wait), returns a sessionId, rendered HTML, and optionally a screenshot
browser_screenshot	Screenshot of a page, optionally after running actions
browser_extract	AI-extracted structured JSON matching a JSON Schema you provide
browser_search	Structured web search results (title/url/snippet) via Zyte's Search API — use to find pages, then open them with browser_browse

browser_browse, browser_screenshot, and browser_extract accept an optional sessionId (returned from a previous call) to reuse the same IP address and cookie jar across multiple tool calls — useful for staying logged in or keeping a consistent IP across a multi-step task. Note that, per Zyte's session docs, this does not persist actual browser/tab state (in-page form input, scroll position, open modals, etc.) between calls — each call loads a fresh page using the same network identity and cookies.

actions is a sequence of steps run before the result is captured: click, type, select, hover, keyPress, scrollBottom, scrollTo, waitForSelector, waitForTimeout, waitForNavigation, goto, evaluate. Element-targeting actions take a selector: { type: "css" | "xpath", value: string }.

browser_search posts to Zyte's separate /v1/search endpoint (not /v1/extract) and takes a domain (a supported search engine, e.g. "google.com"), a query, and optional maxResults (10-100)/geolocation/locale.

Rate-limit (429/503) and temporary-ban (520) responses from Zyte are retried automatically with exponential backoff, up to BROWSER_MAX_RETRIES times, per Zyte's error handling guidance. Other error responses (invalid request, permanent ban, account suspended) surface immediately, with Zyte's error type included in the message where available.

Connecting a client

Example remote-MCP client configuration (e.g. Claude Desktop / Claude Code) pointing at a running instance:

{
  "mcpServers": {
    "browser": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Testing

pnpm test        # unit tests (service + resolver, global fetch mocked)
pnpm run lint    # eslint
pnpm run build   # type-check + compile

Unit tests mock the global fetch used to call Zyte. To verify end-to-end against the live API, run the server with a real ZYTE_API_KEY and use pnpm dlx @modelcontextprotocol/inspector http://localhost:3000/mcp, or curl, to run initialize → tools/list → tools/call.