zenrows-mcp
OfficialSummary: Zenrows MCP gives AI agents managed access to the live web — scraping, structured extraction, bulk batch jobs, crawling, and full browser automation — through one connection.
scrape— fetch any page as Markdown, plain text, HTML, PDF, or screenshot, with automatic JS rendering/premium proxies or forced configurations.extract— pull structured JSON from pages via site-tailoredautomode or explicitcss_extractorselectors.prepare_domain/prepared_domain_status— teachextracta new domain (1–5 example URLs) and poll until ready.Batch tools — submit up to 100,000 URLs asynchronously (
batch_create), then status, wait, page results, read task content, list, cancel/pause/resume, rerun, and delete jobs.Crawl tools — start a crawl from one URL with depth, include/exclude patterns, page/URL limits, and optional stored HTML/Markdown; wait, list results, read content, download to JSONL, or stop.
account_usage— check credit allowance, renewal date, and per-key caps.Browser automation (30+
browser_*tools) — open sessions and navigate, go back/forward/reload, click, hover, type, fill, select, check, focus, press keys, scroll, drag, wait, screenshot, and generate PDFs.Inspection — read the accessibility tree, current URL/title, text, HTML, attributes, and query matching elements.
State & scripting — evaluate JavaScript, read/set/clear cookies, and local storage; manage tabs.
browser_batch— run an ordered sequence of up to 50 browser actions in one call.account_signup_answer— answer Zenrows' signup question to provision a free account and key automatically.
The server can be configured as an MCP tool in OpenAI's Responses API (server_url + authorization), giving OpenAI models live-web scraping, extraction, crawling, batch scraping, and browser automation capabilities against sites that normally block bots.
Zenrows MCP Server
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.
📚 Full documentation: docs.zenrows.com/mcp/overview
Why Zenrows MCP
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.
Related MCP server: @hauntapi/mcp-server
Quick start
Zenrows MCP supports two transport options. Both expose the same set of tools and capabilities. Pick the one that fits your client.
What works without a key:
Local (
npx @zenrows/mcp): no signup, no key. The first tool call creates a Free account (5,000 credits/month) that you can claim later, keeping the key and its usage. Opt out withZENROWS_AUTO_SIGNUP=false. In CI, setZENROWS_API_KEYas a secret or persistZENROWS_HOMEbetween runs.Remote (
https://mcp.zenrows.com/mcp):initializeandtools/listanswer without a key; tool calls need one (OAuth in clients that support it, or a Bearer key). The remote server never creates accounts by itself. A headless agent can create a Free account withPOST https://app.zenrows.com/api/agent/signupand use the returnedapiKeyas the Bearer token. The endpoint may first answer428with a short question; POST{"challenge_id": "...", "answer": "..."}back to the same URL to get the key.
Remote MCP server
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.
Server URL:
https://mcp.zenrows.com/mcpTransport: Streamable HTTP
Authentication: OAuth or API key as Bearer token. Pass your Zenrows API key in the Authorization header on every request (or complete OAuth in clients that support it).
Authorization: Bearer YOUR_ZENROWS_API_KEYMost 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.
Remote MCP does not auto-create accounts.
initializeandtools/listwork without a key; a keyless tool call gets a 401 whose body names the signup endpoint (agent_signup). Use OAuth “Create Free account” in the client, pass an existing API key, or, from a headless agent,POST https://app.zenrows.com/api/agent/signup(anonymous; returnsapiKey, or first a428question to answer withchallenge_idandanswer; per-network limits apply) and retry withAuthorization: Bearer <apiKey>.
Example: OpenAI Responses API
import os
from openai import OpenAI
ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
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.",
)
print(response.output_text)For the full walkthrough with framework-specific examples, see the Remote MCP server docs.
Local MCP server
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.
Package: @zenrows/mcp on npm
Authentication:
ZENROWS_API_KEYenvironment variable, orKey previously stored in
~/.zenrows/secrets.json, orAuto-signup (default): if neither is set, the server still starts, and the first tool call provisions a Free plan account via
POST /api/agent/signup, persists the key + claim metadata under~/.zenrows/(secrets.json+account.json, mode0600), and prints a claim URL on stderr. Zenrows may first ask a short question: the tool call then returns it, and the agent answers with theaccount_signup_answertool, then retries. If signup is refused (for example the per-network cap in CI), that tool call returns an error saying when to retry; in CI, setZENROWS_API_KEYas a secret or persistZENROWS_HOMEbetween runs. Opt out withZENROWS_AUTO_SIGNUP=false: tool calls then return an error until a key is set. The signup request also sends a random per-machine id (shared with the Zenrows CLI) and a guess at the host agent (claude-code,cursor, …) so signups can be attributed; setZENROWS_TELEMETRY=offto omit both.
Requirements: Node.js installed (for npx to work).
Configuration (with your own key):
{
"mcpServers": {
"zenrows": {
"command": "npx",
"args": ["-y", "@zenrows/mcp"],
"env": {
"ZENROWS_API_KEY": "YOUR_ZENROWS_API_KEY"
}
}
}
}Zero-config (auto-signup):
{
"mcpServers": {
"zenrows": {
"command": "npx",
"args": ["-y", "@zenrows/mcp"]
}
}
}Optional: ZENROWS_CRAWL_API_BASE sets the Crawl API base URL for the crawl_* tools (default https://api.zenrows.com/v1). Set it only to point those tools at another deployment.
Optional: ZENROWS_BATCH_API_BASE sets the Batch API base URL for the batch_* tools (default https://async.api.zenrows.com/v1). Set it only to point those tools at another deployment.
Optional: ZENROWS_FETCH_RETRIES lets scrape and extract retry, up to that many times, a call the API did not serve. The default 0 sends each call once. They retry a 429, 502, 503 or 504, and a connection that failed before the request was sent (refused, name resolution, unreachable network or host, connect timeout); every other status or error is returned at once, because the API may have received the request. Each wait is the Retry-After in whole seconds (clamped to 250 ms - 30 s), or else random between 250 ms and 1 s, 2 s, 4 s, ... up to 30 s. A retry starts only if its wait ends within 50 s of the first request, because MCP clients cancel a tool call at about 60 s; a retry that starts near 50 s can still run past that timeout. Each retry writes one line to stderr. The value is read once at start, and anything other than a whole number of 0 or more stops the server. The hosted server retries only if its operator sets it.
The exact location of this config varies by client. See the per-client setup guides for the file path for your client.
Tools
The Zenrows MCP exposes these tool families:
Tool | Purpose |
| Full-page content → Markdown, plain text, HTML, PDF, or screenshot (plus helper outputs). |
| Structured JSON ( |
| Prepare a domain for |
| Cloud Batch API fan-out ( |
| Crawl API ( |
| 30+ tools for full browser automation (navigation, clicks, forms, JS, cookies, tabs, sessions). |
Batch tools
A Batch job scrapes many URLs asynchronously. The usual flow: batch_create, then batch_wait until the run ends, batch_results to page through the rows, and batch_content to read one task's page.
batch_createsubmits one closed job with all its tasks, up to 100,000 per call. Each task takes aurl(http or https, up to 2,048 characters), plus optionalexternal_id(up to 128 characters of letters, digits,.,_and-; need not be unique),metadata(up to 20 string-to-string entries, 4 KiB in all),methodandbodyfor POST tasks (body up to 16 KiB; POST is for read-only queries, since the target can receive a POST more than once), and scrape params, inzenrows_paramsor flat on the task. An unknown task field fails the call by name, before anything is sent.response_typetakesmarkdown,plaintextorpdf; leave it out for HTML. Tasks usemode=autounless you forcejs_renderorpremium_proxy. Every call sends anIdempotency-Key, generated unless you setidempotency_key: a repeat with the same key and body within 24 hours returns the original job instead of a second one, and a different body isBATCH_IDEMPOTENCY_CONFLICT. An error reply carries the key to retry with. Setwait: trueto return when the run ends or pauses, or whenwait_timeout(seconds, default 50) passes.batch_statusandbatch_waitreport the latest run'sstatus(pending,running,completed,stopped,failed) andstats.batch_waitpolls until the run ends, returns at once withpaused: trueon a paused run, and tolerates transient errors. Itstimeoutis in seconds (default 50, under the 60 seconds after which many clients cancel a call); when it runs out, the reply is the current state withok: true,timed_out: trueand a note, not an error. A call with aprogressTokengets a progress notification after each poll. A run still writing its tasks (submits of 10,000 or more, and every rerun) hasingesting: true.batch_resultsreturns up tolimitrows (default 100, max 1,000) and anext_cursor; pass it back ascursoruntil it isnull. Filter withstatus:all,successful,failedorprocessing. Passrun_idfor an earlier run. A row'sresult_urlis presigned for 2 hours: list again, or usebatch_content, for a fresh one. Results are kept 14 days by default; after that a successful row reads asexpired, with noresult_url.batch_contentreturns one task's result. Text (HTML, Markdown, plain text, JSON) comes back inline, cut tomax_chars(default 20,000); a PDF comes back as its presignedresult_url; on a large run, finding it can take more than one call, and the reply then carrieslookup_cursorto pass back. A task not finished yet isBATCH_TASK_NOT_READY, a failed oneBATCH_TASK_FAILED(withtask_error), an expired oneBATCH_RESULT_EXPIRED.batch_listlists the account's jobs, newest first (default 20 per page, max 100).batch_cancelstops the current run for good: no waiting task starts, in-flight tasks finish and bill, results stay.batch_pausehalts it untilbatch_resume; a paused run still counts as an active job. All three are idempotent, and on a run that already ended they answer with its final state andalready_ended: true.batch_rerunstarts a new run once the latest one ended. By default it reruns thefailedandpendingtasks and carries the others over: the recovery after a run that ran out of credits or was cancelled. Passstatusfor other task statuses, orfull: trueto scrape every task again. A partial rerun works up to 10 days after the run started. It sends anIdempotency-Key.batch_deletedeletes a job with its runs and results, and frees its active-job slot.
Costs: the same credits as the regular API, per successful task: 1 basic, 5 with js_render, 10 with premium_proxy, 25 with both; mode=auto bills each task at the configuration that worked. Failed tasks are not billed, except target 404 and 410 answers. An account runs 3 active jobs at once by default, shared with Crawl.
A run that ends failed answers ok: false, with error.code the same as the matching HTTP error (BATCH_INSUFFICIENT_CREDITS, BATCH_KEY_CAP_REACHED, or AUTH_INVALID for an inactive subscription; BATCH_RUN_FAILED otherwise), error.server_code (the failure_reason), error.job_id and advice. Fix the cause, then batch_rerun.
Errors carry code, message, detail, server_code (the Batch API's own code) and, for a call about one job, job_id:
Code | When |
| 400: the request was rejected; |
| 401: the API key was rejected, or, with |
| 402: the account has no credits left. |
| 402: this API key reached one of its credit caps; the account's other keys still work. |
| 403: Batch is not enabled for this account or key. Do not retry. |
| 404: no such job, run or task for this account (a deleted job included). |
| 409, by |
| 410: past the job's retention. |
| 422: the task failed; |
| 429: a job limit more credits do not raise (3 active jobs, shared with Crawl; 5 scheduled jobs). |
| Any other 429. |
| Any other HTTP error. |
| No response: a network error or timeout, after retries. |
Reads retry on 429, 500, 502, 503, 504 and network errors, up to 3 times, honoring Retry-After up to 30 seconds. batch_create and batch_rerun retry on 500, 502, 503, 504, network errors and a 429 with Retry-After, always with the same Idempotency-Key; never on the job-limit 429. On BATCH_IDEMPOTENCY_CONFLICT for the same request, keep the key, check batch_list and retry later: a new key can create a second, billed job.
Schedules, webhooks, results exports, CSV inputs, open jobs (adding tasks over time), runs and task history are available through the Batch API and the Zenrows SDKs only.
The AI selects the right tool from your prompt. You don't call tools directly in code.
See the full tool reference for every tool, parameter, and return value.
Development
git clone https://github.com/ZenRows/zenrows-mcp
cd zenrows-mcp
npm install
cp .env.example .env # Optional: add your API key (stdio can auto-signup)
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 UIRunning the Crawl end-to-end test
npm test stays offline. npm run test:e2e drives the crawl_* tools through a real MCP client against a live Crawl API: it creates a small crawl (depth 1, at most 3 URLs and 5 pages) of the start URL you give it, waits for it, reads its results and one page, lists crawls, stops the ended crawl, and checks the not-found error. It is skipped unless the first three variables are set:
ZENROWS_API_KEY: a key with Crawl access.ZENROWS_CRAWL_API_BASE: the Crawl API base, e.g.https://api.zenrows.com/v1. Point it at a local or staging deployment to test against that instead.ZENROWS_E2E_CRAWL_URL: the start URL to crawl, a listing page whose links lead to item pages.ZENROWS_E2E_CRAWL_INCLUDE(optional): an include pattern; when set, the test checks that every result URL contains it.
export ZENROWS_API_KEY=... # a key with Crawl access
export ZENROWS_CRAWL_API_BASE=https://api.zenrows.com/v1
export ZENROWS_E2E_CRAWL_URL=https://example.com/products/
export ZENROWS_E2E_CRAWL_INCLUDE=/product/
npm run test:e2eThe crawl is billed to the key's account (at most 5 page fetches), and it counts against the account's limit of active jobs (3 by default), shared with its Batch jobs. When the account has reached that limit, the test waits and retries for up to 5 minutes.
Releases
Merge PRs with Conventional Commit titles, for example fix(extract): ... or
feat(crawl): .... fix, feat and perf need a scope.
After each merge to main, release-please opens or updates the PR
chore: release X.Y.Z. It sets the version in package.json,
package-lock.json and server.json. Do not change these by hand.
To release, merge that PR. The Release workflow runs the checks, creates the
tag vX.Y.Z and the GitHub release, and starts the Publish workflow. That
workflow publishes to npm and the MCP Registry, pushes the GHCR image and
deploys the hosted server.
To publish an existing tag again, run the Release workflow by hand from
main with that tag.
If the checks fail after the release PR is merged
The release PR runs CI like any other PR. After you merge it, the release
run checks the code again before it tags and publishes. If that check
fails, main already has the new version, but there is no tag, and the
merged release PR keeps the autorelease: pending label, which blocks the
next release PR. To recover:
Fix the problem in a normal PR and merge it.
Create the release on that fix commit, with the version from
.release-please-manifest.json:gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag>On the merged release PR, replace the label
autorelease: pendingwithautorelease: tagged.Run the Release workflow by hand from
mainwith the tagvX.Y.Z.
Pull requests and issues are welcome.
Resources
License
Available Tools
63 toolsaccount_signup_answerAInspect
Answer the question Zenrows asks before it creates a free account. Use it only when another Zenrows tool reports a signup question: answer that question yourself and pass the answer here. On success the API key is stored and you can retry the original tool call.
Inputs: answer (required).
account_usageARead-onlyInspect
Read the current plan's credit allowance and how much of it is spent.
Useful before a large batch, or after a 402 / AUTH004, to see whether the account has credits left and when the allowance renews. The call is free and does not use a concurrency slot.
Credit costs per request: 1 basic, 5 js_render, 10 premium_proxy, 25 both.
AUTH004 ("usage exceeded") means this allowance is spent until it renews at the end of the billing period (period_ends_at in this tool's response). Plans and credit options are described at https://www.zenrows.com/pricing. AUTH006 is the concurrency limit, not a credit limit.
AUTH014 (Batch: api_key_cap_reached) means this API key hit one of its own credit caps while the account still has credits; other keys keep working. The response's api_key.caps lists the calling key's caps: window, credits, used_credits, remaining_credits, resets_at, and unavailable (usage could not be read). Caps are managed at https://app.zenrows.com/settings/api-keys.
Inputs: no named parameters.
batch_cancelADestructiveIdempotentInspect
Stop a Batch job's current run for good. No task still waiting is started or billed; tasks already in flight finish (and bill). Results so far stay readable with batch_results. Tasks that never started stay pending: batch_rerun (default failed and pending) runs them later. Idempotent: a run that already ended answers with its final status and already_ended:true. To halt without ending the run, use batch_pause.
Inputs: job_id (required).
batch_contentARead-onlyInspect
Read one Batch task's stored result, by job_id and task_id (from batch_results). A text result (HTML, Markdown, plain text, JSON) comes back inline, cut to max_chars (default 20000); a final note says when it was cut. A binary result (a PDF) is not inlined: the reply gives its result_url, presigned for 2 hours. Finding that URL reads the run's results; on a large run one call may run out of time first and answer with lookup_cursor: call batch_content again with it to go on.
BATCH_TASK_NOT_READY: the task has not finished; BATCH_TASK_FAILED: it failed (task_error holds its error); BATCH_RESULT_EXPIRED: past the job's retention (14 days by default); rerun to scrape it again.
Inputs: job_id (required), task_id (required), run_id, max_chars, +1 more.
batch_createAInspect
Submit a Batch job: many URLs scraped asynchronously in the cloud (Zenrows Batch API). Suited to large URL lists; scrape and extract handle single pages. Not the same as browser_batch.
Tasks use automatic mode (mode=auto) by default: Zenrows enables JS rendering and premium proxies only on the pages that need them. Pass just the URLs. Set js_render or premium_proxy (job-level, or per task) only to force a fixed configuration; that turns automatic mode off for those tasks.
Cost: the same credits as the regular API, per successful task: 1 for a basic request, 5 with js_render, 10 with premium_proxy, 25 with both; mode=auto bills each task at the configuration that worked. Failed tasks are not billed, except target 404 and 410 answers, billed as on the regular API. Limits: up to 100,000 tasks per call; 3 active jobs per account by default, shared with Crawl (BATCH_QUOTA_EXCEEDED past that); a job frees its slot when its run ends.
Creates a closed job with every task in this one call. Each task takes a url plus optional external_id, metadata, method/body (POST tasks) and scrape params. Every call sends an Idempotency-Key, so the bounded retries on network errors and 5xx never create a second job; an error reply carries the key to retry with.
Returns job_id, status and stats at once; the job runs asynchronously. Then: batch_wait until it ends, batch_results to list rows (paged), batch_content to read one task's page. A run that ends failed (out of credits, inactive subscription, key cap) answers ok:false with error.code and server_code; batch_rerun recovers it. Submits of 10,000+ tasks keep writing tasks for a while (ingesting:true). Errors: BATCH_INVALID_REQUEST (400, server_code and invalid_tasks say what), BATCH_INSUFFICIENT_CREDITS (402), BATCH_KEY_CAP_REACHED (402, this key's cap), BATCH_QUOTA_EXCEEDED (429, job limit), AUTH_INVALID (401; server_code subscription_inactive means fix Billing), BATCH_ACCESS_DENIED (403, do not retry), BACKEND_UNAVAILABLE. Schedules, webhooks, exports, CSV inputs and open jobs are available through the Batch API and SDKs only.
Inputs: urls, wait, tasks, js_render, +8 more.
batch_deleteADestructiveIdempotentInspect
Delete a Batch job with all its runs and results, for good. A run in flight stops picking up tasks at once, and the job frees its active-job slot. The job reads as not found right away; storage is cleaned up in the background. Idempotent. To keep the results, use batch_cancel instead.
Inputs: job_id (required).
batch_listARead-onlyInspect
List this account's Batch jobs, newest first, each with its latest run's status and stats. Filter by status (open or closed) and type (regular or scheduled). Pass next_cursor as cursor for the next page; a page can hold fewer than limit jobs while next_cursor is still set, so keep paging until it is null. Deleted jobs are not listed.
Inputs: type, limit, cursor, status.
batch_pauseAIdempotentInspect
Pause a Batch job's current run: it picks up no new tasks until batch_resume. Tasks already in flight still finish and bill; for a hard cost stop use batch_cancel. A paused run still counts as an active job. Idempotent; a run that already ended answers with its final status and already_ended:true.
Inputs: job_id (required).
batch_rerunAInspect
Start a new run of a Batch job whose latest run ended (completed, stopped or failed). By default it reruns only the tasks that failed or never started (status ["failed", "pending"]), and carries the others' results over: the recovery after a run that failed on credits or was cancelled. Pass status to pick other task statuses, or full:true to scrape every task again. Rerun tasks are billed like new ones.
A rerun of only some tasks works up to 10 days after the run started (BATCH_RERUN_WINDOW_EXPIRED after that; full:true still works). BATCH_NO_MATCHING_TASKS: no task has those statuses. BATCH_RUN_NOT_FINISHED: the latest run is still in flight. Sends an Idempotency-Key, so a retry never starts two runs. Returns the new run at once (it writes its tasks first, ingesting:true); call batch_wait.
Inputs: job_id (required), full, status, idempotency_key.
batch_resultsARead-onlyInspect
List a Batch run's result rows, a page at a time: up to limit rows (default 100, max 1000) and next_cursor. Pass next_cursor back as cursor to continue; it is null once every row was read.
Each row has task_id, external_id, url, metadata, status (successful, failed, pending, processing, expired), type, result_url when successful, and error when failed. A result_url is presigned and expires after 2 hours: call batch_results again for a fresh one, or read the body with batch_content. Results are kept 14 days by default; after that a successful row reads as status "expired", with no result_url, and batch_content answers BATCH_RESULT_EXPIRED.
Filter with status: all (default), successful, failed, or processing (not finished yet). A sparse filter can return fewer rows than limit with next_cursor still set: keep paging. While the run is still running or writing its tasks, the list is partial.
Inputs: job_id (required), limit, cursor, run_id, +1 more.
batch_resumeAIdempotentInspect
Resume a paused Batch run: it picks up its remaining tasks again, billed as they finish. Idempotent on a run that is not paused; a run that already ended answers with its final status and already_ended:true. Needs credits: BATCH_INSUFFICIENT_CREDITS or BATCH_KEY_CAP_REACHED otherwise.
Inputs: job_id (required).
batch_statusARead-onlyInspect
Get a Batch job's latest run: job_id, run_id, status (pending, running, completed, stopped, failed), stats (total, completed, successful, failed) and the job.
A failed run answers ok:false with error.code BATCH_INSUFFICIENT_CREDITS, BATCH_KEY_CAP_REACHED, AUTH_INVALID (subscription_inactive) or BATCH_RUN_FAILED, error.server_code (the failure_reason) and failure_detail; batch_rerun recovers it once fixed. A paused run has paused:true; one still writing its tasks has ingesting:true.
Inputs: job_id (required).
batch_waitARead-onlyInspect
Poll a Batch job until its run ends (completed, stopped or failed) or pauses, and return its status and stats like batch_status. If the wait runs out first, it returns the current state with ok:true, timed_out:true and a note: call batch_wait again. A paused run returns at once with paused:true (it does not move until batch_resume). A failed run answers ok:false with error.code and server_code (insufficient_credits, subscription_inactive or api_key_cap_reached). Transient poll errors are retried. A call that carries a progressToken gets a progress notification after each poll.
Inputs: job_id (required), timeout, timeout_ms.
browser_batchADestructiveInspect
Execute a sequence of browser actions in a single call against an existing session.
Use this when you already know the full sequence of steps — it reduces round trips and is faster than calling each tool individually.
Actions run sequentially and stop at the first failure unless stop_on_error is false. Each step result is returned in the results array at the same index.
Note: screenshots in batch results are returned as base64 strings inside the JSON; browser_screenshot returns them as images.
A batch can include evaluate, so it can change or delete page state the same way browser_evaluate can.
Inputs: actions (required), session_id (required), stop_on_error.
browser_checkCInspect
Check a checkbox or radio button.
Inputs: selector (required), session_id (required).
browser_clear_cookiesBDestructiveInspect
Clear all cookies for the current browser session.
Inputs: session_id (required).
browser_clear_local_storageADestructiveInspect
Delete every localStorage entry in the current page context.
Inputs: session_id (required).
browser_clickBInspect
Click an element on the page using a CSS selector.
Inputs: selector (required), session_id (required).
browser_closeAInspect
Close a browser session and free all associated resources, including the concurrency slot it holds.
Inputs: session_id (required).
browser_dragCInspect
Drag an element from its current position to a target element.
Inputs: session_id (required), source_selector (required), target_selector (required).
browser_evaluateADestructiveInspect
Execute JavaScript in the browser context and return the result. The script can change or delete the session's page state, such as cookies, storage and form data.
Inputs: script (required), session_id (required).
browser_fillAInspect
Clear an input field and set its value, replacing what was there (browser_type appends instead).
Inputs: value (required), selector (required), session_id (required).
browser_focusBInspect
Move focus to an element, triggering focus-dependent UI changes.
Inputs: selector (required), session_id (required).
browser_generate_pdfCRead-onlyInspect
Render the current page as a PDF document.
Inputs: session_id (required), scale, landscape, print_background.
browser_get_accessibility_treeARead-onlyInspect
Get the ARIA accessibility tree of the current page as readable text.
Shows the page structure and the selectors needed to interact with elements, in fewer tokens than a screenshot.
The tree shows all interactive elements (buttons, inputs, links) with their roles, labels, and states — everything needed to drive browser interactions.
Inputs: session_id (required).
browser_get_attributeBRead-onlyInspect
Get the value of a specific attribute on an element.
Inputs: selector (required), attribute (required), session_id (required).
browser_get_cookiesBRead-onlyInspect
Get all cookies for the current page.
Inputs: session_id (required).
browser_get_htmlCRead-onlyInspect
Get the HTML source of an element or the full page.
Inputs: session_id (required), selector.
browser_get_local_storageARead-onlyInspect
Read one localStorage value in the current page context.
Inputs: key (required), session_id (required).
browser_get_textBRead-onlyInspect
Get the visible text content of an element or the entire page body.
Inputs: session_id (required), selector.
browser_get_titleARead-onlyInspect
Get the title of the current page.
Inputs: session_id (required).
browser_get_urlBRead-onlyInspect
Get the current URL of the browser session.
Inputs: session_id (required).
browser_go_backBInspect
Navigate back to the previous page in the browser history.
Inputs: session_id (required).
browser_go_forwardBInspect
Navigate forward to the next page in the browser history.
Inputs: session_id (required).
browser_hoverBInspect
Move the mouse cursor over an element to trigger hover effects.
Inputs: selector (required), session_id (required).
browser_new_tabAInspect
Open a new browser tab. Returns a tab_id to use with browser_switch_tab.
Inputs: session_id (required), url.
browser_press_keyCInspect
Press a keyboard key. Examples: "Enter", "Tab", "Escape", "ArrowDown", "Control+a".
Inputs: key (required), session_id (required).
browser_query_selector_allBRead-onlyInspect
Find all elements matching a CSS selector and return their text, HTML, and attributes.
Inputs: selector (required), session_id (required).
browser_reloadBInspect
Reload the current page of a browser session.
Inputs: session_id (required).
browser_screenshotARead-onlyInspect
Take a screenshot of the current page or a specific element. Use for visual verification or when the accessibility tree is not sufficient.
Inputs: session_id (required), selector, full_page.
browser_scrollCInspect
Scroll the page in a given direction.
Inputs: direction (required), session_id (required), distance.
browser_select_optionCInspect
Select an option from a dropdown element.
Inputs: value (required), selector (required), session_id (required).
browser_set_cookiesADestructiveInspect
Set one or more cookies in the browser session. A cookie with the same name, domain and path replaces the existing one.
Inputs: cookies (required), session_id (required).
browser_set_local_storageADestructiveInspect
Write one localStorage value in the current page context. An existing value under the same key is replaced.
Inputs: key (required), value (required), session_id (required).
browser_switch_tabCInspect
Switch focus to a different browser tab.
Inputs: tab_id (required), session_id (required).
browser_typeAInspect
Type text into an input element. Appends to existing content unless clear_first is set.
Inputs: text (required), selector (required), session_id (required), clear_first.
browser_uncheckAInspect
Uncheck a checkbox, found by CSS selector, in a browser session.
Inputs: selector (required), session_id (required).
browser_waitARead-onlyInspect
Wait for a fixed duration. browser_wait_for_selector waits only until an element appears.
Inputs: ms (required), session_id (required).
browser_wait_for_selectorBRead-onlyInspect
Wait until an element matching the CSS selector is stable in the DOM. Set visible=true to also require the element to be visible (not hidden).
Inputs: selector (required), session_id (required), visible.
crawl_contentARead-onlyInspect
Read the stored page of one URL a crawl kept, in the crawl's output_format. Works only for crawls created with an output_format, and only for results whose content_status is fetched.
Pass crawl_id and content_id: a content id, or content_url from a crawl_results row. Returns the page as stored — raw HTML for output_format "html", Markdown for "markdown" — cut to max_chars (default 20000); a final note says when it was cut. To read a page the crawl did not store, use scrape on its URL instead.
Inputs: crawl_id (required), content_id (required), max_chars.
crawl_createAInspect
Start a crawl from one URL (Zenrows Crawl API). Crawl follows the links in each page's HTML up to depth hops (no depth limit when depth is omitted), keeps the URLs that match include_patterns / exclude_patterns, and stays on the start URL's registrable domain (subdomains count).
Use crawl when you have one start page (a listing, category, blog index) and need the URLs behind it, optionally with each page's HTML. For a single page, use scrape.
Each page fetched is billed as one scrape on this account; max_pages bounds the cost (default 100), max_items bounds how many URLs are kept (default 100). Without depth, the crawl keeps following links until max_pages or max_items stops it or nothing is left to open, so set max_pages to what you are willing to spend. The start page itself is never a result, but its fetch is billed: a crawl whose include_patterns / exclude_patterns match nothing still costs that one scrape. A crawl whose pages held nothing new to follow (no link, only links to other sites, or only links the patterns reject) ends completed with no results and no error. When patterns are set, check them against the URLs the start page links to. Set output_format "html" or "markdown" to also store each kept URL's page, then read it with crawl_content. Set webhook to have signed events posted to your https URL when the crawl starts and when it ends; the account needs a webhook signing key, else CRAWL_INVALID_REQUEST (webhook_signing_key_required).
Returns crawl_id, status and the crawl (with coverage) at once; the crawl runs asynchronously. Call crawl_wait, then crawl_results. Set idempotency_key to make a retry safe: the same key returns the crawl the first request created instead of starting another. CRAWL_NOT_ENABLED: Crawl is not enabled for this account; do not retry. CRAWL_TOO_MANY_CRAWLS: the account has reached its limit of active jobs (3 by default), shared with its Batch jobs; retry after retry_after seconds.
Inputs: url (required), depth, webhook, discovery, +6 more.
crawl_downloadAInspect
Save every result of a crawl to one local file, as JSON lines: url, content_status and, once fetched, content (the page). Returns the file's path and line count, not the results, so a crawl of any size costs one small reply. Read the file with your own tools.
The file goes to path when given (a relative path inside ~/.zenrows/crawls; an absolute path or one that leaves that folder fails with INVALID_PATH), else ~/.zenrows/crawls/<crawl_id>.jsonl. An existing file is kept and the call fails with FILE_EXISTS unless overwrite is true.
On a running crawl the file holds only what was kept so far: download again once crawl_wait says it ended. After crawl_stop, pages in flight can still add lines for up to 10 minutes: the reply says so with partial: true. On the hosted server no file is written: the reply gives the download URL and a command to run where your API key is set.
Inputs: crawl_id (required), path, overwrite.
crawl_getARead-onlyInspect
Get a crawl and one page of the URLs it kept: crawl_id, status (running, completed, stopped, failed), the crawl (with coverage: pages_fetched, pages_failed, items_found; webhook when set), results and next_cursor.
completed with stop_reason max_items / max_pages means a limit ended it; stopped with stop_reason user means crawl_stop ended it; stopped with no stop_reason and error.code insufficient_credits or api_key_cap_reached means the account ran out of credits or the API key hit a credit cap (the URLs kept before that stay readable); completed with no results and no error means the crawl's pages held nothing new to follow; when include_patterns / exclude_patterns are set, check them against the URLs the start page links to. failed carries error.code and error.detail: seed_unreachable means the start URL could not be fetched or returned an empty page; no_items_found means the crawl read the start page but found no data it could use, so it had nothing to follow; start from a listing or product page. A failed crawl, and a stopped one with an error, answer ok: false: error.code is CRAWL_INSUFFICIENT_CREDITS or CRAWL_KEY_CAP_REACHED (the codes crawl_create gets on a 402) when credits ended it, failed or stopped, else CRAWL_FAILED; error.server_code is the crawl's error.code. Pass next_cursor as cursor for the next page; while the crawl runs, next_cursor is never null. To read many pages at once, use crawl_results.
Inputs: crawl_id (required), limit, cursor.
crawl_listARead-onlyInspect
List this account's crawls, newest first, with status and coverage (no results). Pass next_cursor as cursor for the next page; next_cursor is absent on the last page.
Inputs: limit, cursor.
crawl_resultsARead-onlyInspect
List the URLs a crawl kept, in the order it kept them, following the API's pages up to limit.
Each result has url and, when the crawl has output_format, content_status (pending, fetched, failed) and, once fetched, content_url: pass it to crawl_content as content.
While the crawl runs the list is partial (partial=true): call again later with the returned next_cursor to get only the URLs kept since. A stopped crawl can still add URLs from pages fetched before the stop for up to 10 minutes, so next_cursor stays set during that window: call again later. next_cursor is null once the crawl ended and every URL was read.
Inputs: crawl_id (required), limit, cursor.
crawl_stopADestructiveIdempotentInspect
Stop a running crawl. No page still waiting is fetched or billed; pages already in flight finish. The URLs kept so far stay readable with crawl_results. A stopped crawl cannot resume.
Idempotent: a crawl that already ended answers with its final status. A 429, 502, 503 or 504 is retried up to 3 times, waiting at most 50 seconds in all; a 503 crawl_busy means the stop was not saved yet, and if it persists, CRAWL_BUSY says when to call again. Pages in flight still finish, so coverage and results can keep growing for up to 10 minutes after the stop; read them with crawl_get and crawl_results.
Inputs: crawl_id (required).
crawl_waitARead-onlyInspect
Poll a crawl until it ends (completed, stopped, or failed) and return its status, its counts and the first 20 URLs (first_urls). For every result, call crawl_download (one file) or crawl_results (pages). A crawl that ends completed with no results and no error finished; it is not a failure (see crawl_get). If the wait runs out first, it returns the crawl with status running and a note: call crawl_wait again. A call that carries a progressToken gets a progress notification after each poll, with the status and counts.
Inputs: crawl_id (required), timeout.
extractARead-onlyInspect
Extract structured data from a webpage via Zenrows.
Returns JSON fields (products, articles, listings) in "data" rather than a full page body. Set include_html to also get the page HTML. Modes:
auto (default): extract=auto, site-tailored Extract (currently free, billing may apply later). Works on any prepared domain, with any API key. Error REQS007 says why in "reason":
domain_not_prepared: call prepare_domain with the domain and 1 to 5 example URLs (one works; we recommend 3 or more of the same page type; a few minutes, no credits), poll prepared_domain_status about every 30 seconds until it says ready, then call extract again.
page_not_recognised: the domain is prepared, but this page is not one Extract extracts (a page with nothing to extract, such as a home page). Try a product, article or listing page instead; if this page should work, retry it once in a few minutes; otherwise use mode=css. Do not prepare the domain again.
domain_not_enabled: preparing does not help; use mode=css.
autoparse: deprecated general-purpose structured JSON on any domain; use only when asked for
css: css_extractor with an explicit selector map
Requests use automatic mode (mode=auto) by default: Zenrows enables JS rendering and premium proxies only when the site needs them, and charges only for the configuration that succeeds. Pass just the URL. Set js_render or premium_proxy only to force a fixed configuration; that turns automatic mode off and bills every request at that configuration's cost.
Check "empty" in the result: true means no field came back with a value. "noDataExtracted": true means Extract processed the page and found nothing to extract (not charged); retrying the same request returns the same answer. Full-page markdown, HTML and screenshots come from scrape.
Inputs: url (required), mode, wait, wait_for, +7 more.
prepared_domain_statusARead-onlyInspect
Check a domain submitted with prepare_domain, and the account's monthly allowance.
Returns status (preparing, ready or failed), state (the current step), roles (one per page kind), a failure code and detail when it failed, the allowance (used, limit, remaining) and "next": what to do now. Poll about every 30 seconds; preparation takes a few minutes. Call extract again once status is "ready". Costs no credits.
Inputs: domain (required).
prepare_domainAIdempotentInspect
Prepare a domain so extract (mode=auto) works on it.
Use this when extract returns error REQS007 with reason domain_not_prepared. Send the domain (the host, e.g. shop.example.com; a leading www. is dropped, and each host is prepared separately) and 1 to 5 example URLs of real pages you want extracted. One works; we recommend 3 or more of the same page type, so pass 3 or more when you can, up to 5 (e.g. 3 product pages: https://www.example.com/products/a, /products/b and /products/c), because Extract compares pages of one type to check the fields it found and fill in fields one page is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result pages). It returns at once with status "preparing" and never waits; preparation takes a few minutes and costs no credits. Then call prepared_domain_status about every 30 seconds until status is "ready", and call extract again. Each new domain uses one slot of the account's monthly allowance (prepared_domain_status shows it). A domain already being prepared returns its current status; a domain already prepared returns "ready" at once with already_prepared: true and uses no slot.
Do not call this for REQS007 with reason page_not_recognised: the domain is already prepared and preparing again does not change that answer.
Inputs: domain (required), example_urls (required), idempotency_key.
scrapeARead-onlyInspect
Scrape any webpage and return its content using Zenrows (Fetch).
Returns full-page content (markdown/HTML/PDF/screenshot). For structured JSON fields (products, articles, listings), the extract tool returns parsed fields instead of a full page body.
By default the request uses automatic mode (mode=auto): Zenrows adds JS rendering or premium proxies per page only when a plain request does not return the page, and charges only for the configuration that succeeds. Pass just the URL.
Set js_render or premium_proxy only to force a fixed configuration. Doing so switches off automatic mode, and every request is billed at that configuration's cost (premium_proxy with js_render is 25x a basic request).
Examples: Default: { url: "https://example.com" } Geo: { url: "https://example.com", proxy_country: "US" } Forced: { url: "https://spa.com", js_render: true }
Inputs: url (required), wait, outputs, wait_for, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
The browser_* family is granular but the descriptions actively disambiguate overlapping pairs (browser_fill vs browser_type, browser_get_text vs browser_get_html vs browser_get_attribute vs browser_query_selector_all, the three browser_wait variants). Cross-references also clarify scrape vs extract vs batch_create vs crawl_create and batch_status vs batch_wait. A few reading/waiting tools and crawl_get vs crawl_results still border on overlap, but an agent can reliably select the right tool.
Everything is snake_case with clear namespace prefixes (browser_, batch_, crawl_, account_) that map to the platform's sub-APIs, and most tools follow verb_noun (browser_click, batch_create, crawl_wait). Minor deviations exist: crawl_results and crawl_content are noun phrases among verb-prefixed crawl tools, and scrape/extract/prepare_domain/prepared_domain_status depart from the prefixed scheme.
63 tools is very heavy and well beyond the 3-15 sweet spot; an agent must wade through ~38 browser_* tools before reaching scrape/extract/batch/crawl. The breadth is legitimately backed by four distinct sub-APIs (browser, scraper, batch, crawl), so it is not a trivial-scope mismatch, but the surface is large enough to burden selection and context.
The surface covers full lifecycle for every sub-API: browser automation (navigate, interact, tabs, storage/cookies, waits, evaluate, screenshot/PDF, close), scraping (scrape, extract, prepare_domain + status), batch (create, wait, status, results, content, pause/resume/cancel/rerun/delete, list), and crawl (create, wait, get, results, content, download, stop, list), plus account usage and signup. No obvious dead ends for the stated platform scope.
Maintenance
Related MCP Connectors
Web scraping MCP server — scrape, extract structured data, screenshot any site with anti-bot bypass.
Web scraping MCP server: any URL to Markdown or JSON, with JavaScript rendering and batch jobs.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Unofficial ScrapingBee MCP — wraps the ScrapingBee headless-scraping API (scrapingbee.com)
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP-native web scraping and search API for AI agents. Converts any URL to clean Markdown with 90% success rate, including Cloudflare-protected sites and JS SPAs. Real-time web search via Brave Search API. CAPTCHA solving built-in. 10 free scrapes/day.55MIT
- AlicenseAqualityBmaintenanceWeb extraction MCP server for AI agents. Extract structured data from any URL with built-in Cloudflare bypass, JavaScript rendering, and intelligent parsing. Returns clean markdown or JSON.5794 npm2MIT
- AlicenseNot gradedqualityBmaintenanceRemote MCP server for web scraping with anti-bot evasion. Provides stealth HTTP fetching, headless browser with Cloudflare bypass, CSS selectors, YouTube transcripts, and Markdown conversion.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server to scrape web pages to clean Markdown via headless Chromium, with support for single or batch URLs.MIT