MrScraper MCP server for AI agents

Run an existing manual (workflow) scraper across many URLs in one asynchronous bulk job. The vendor reference says reruns reuse cached results, which can reduce token usage and improve execution time; not observed in testing. Returns data.bulkResultId, the id of the bulk job, with the message 'Bulk scraping is Running'; no extraction results come back in this response. Poll that id with mrscraper_get_result: status is Running while URLs are processed and becomes Finished (or Cancelled or Failed). The polled record's data holds mergedData (extraction output per page), urlDetails (status and error for each URL) and a summary of totalUrls, successfulUrls, failedUrls, scrapedCount, totalTokenUsage and estimatedFinishAt. Rely on status, not on mergedData or urlDetails, to know the job is done (the vendor reference says they fill in as URLs finish). estimatedFinishAt was null in every summary seen in testing. Finished means the job ended, not that every URL succeeded: read summary.failedUrls and each urlDetails status. Use this for many URLs and mrscraper_rerun_manual_scraper for a single URL. Stop a running job with mrscraper_cancel_bulk_result using the bulkResultId. Successful URLs consume plan tokens (10 per URL in the AI-scraper jobs seen in testing; the cost of a manual-scraper URL was not observed), so check tokenLimit and tokenUsage with mrscraper_verify_api_token before submitting a long list. Requires the scraperId of a manual scraper that already exists in the MrScraper account, typically one built for item detail pages; this connector has no tool to create one. In testing an AI scraper's id was accepted and the job then ended Failed with zero tokens.

Cancel one running bulk scraping job by its bulk result id. Returns data with id (the scraperId of the job's scraper, not the bulk result id), bulkUrls (every URL in the job) and canceledUrls (the URLs that were stopped). canceledUrls is empty when the job had already finished. Afterwards mrscraper_get_result shows the job's status as Cancelled. Use this to stop a single bulk run, using the bulkResultId returned by mrscraper_bulk_rerun_ai_scraper or mrscraper_bulk_rerun_manual_scraper. Requires the bulkResultId from a bulk rerun response; mrscraper_get_result shows the job's current status. Do not call it on a job that has finished: the call still succeeds, with empty canceledUrls, but in testing it overwrote the finished job's saved status with Cancelled (tokens already spent stayed on the record); check mrscraper_get_result first and cancel only while status is Running.

Cancel the remaining pending URLs of the running bulk scraping job for a scraper. Per the vendor reference (no successful response was seen), returns the record id (id), the full list of URLs in the bulk job (bulkUrls) and the URLs that were canceled (canceledUrls), which can be fewer than bulkUrls. Documented to stop all pending URLs for a scraper at once, but the route does not work today (see below); use mrscraper_cancel_bulk_result to cancel one bulk run by its bulk result id. Requires the scraperId that was used for the bulk rerun (mrscraper_bulk_rerun_ai_scraper or mrscraper_bulk_rerun_manual_scraper). Caveat: this documented route answered 404 Not Found on MrScraper's live API on 2026-10-22, checked with a real scraper id, so the call fails until MrScraper serves it; use mrscraper_cancel_bulk_result with the bulkResultId instead.

Create a reusable AI scraper from a natural-language prompt and run it once against a URL, using the general, listing or map agent. Returns the result record: result id, scraperId, type, url, status, error, tokenUsage, runtime and the extracted data for the chosen agent (seen in testing: general, an object of page-level fields with the items in a products list; map, a count and a urls list; listing, a response list with one entry for the page). The vendor reference describes this first run as generating example output only; in testing a prompt asking for the first three books returned all 20 products on the page. Use this to set up a scraper you will rerun: save its scraperId, then use mrscraper_rerun_ai_scraper for one URL or mrscraper_bulk_rerun_ai_scraper for many URLs. For a one-off extraction that returns the data in a single call, use mrscraper_scrape_json (general agent, one page) or mrscraper_scrape_sitemap (map agent, URL discovery); both can run close to Scalekit's 10-second limit, see their descriptions. mrscraper_scrape_listing_page covers multi-page listings, but no run of that tool completed in testing (the listing agent finished once, through this tool, on a single page). Each run consumes MrScraper plan tokens. Creation took 19 to 39 seconds in the 3 creations tested (all on one site), longer than Scalekit's 10-second call limit, so this tool returns a timeout error even though the scraper is created and runs, and its response was never seen; recover the scraperId from the newest record of type AI in mrscraper_list_results (sorted by createdAt descending). That record appeared only when creation finished, 19 to 39 s after the call started, and the test waited 40 s after the timeout before listing; listing sooner returns an older scraper's record or none, so check that the record's url matches yours and that its createdAt is later than your call.

Get scrape status counts for one domain within a date range, for one action label, optionally filtered by API token name. Returns a summary with countAll, successRate, reqPerMinute and avgLatency, plus a list of key and value pairs counting scrapes by status (COMPLETED, PENDING and FAILED came back in testing, with the counts as strings). Use this to see how scraping for a domain is performing over a period (the dates carry no timezone parameter, and the timezone MrScraper applies was not tested). Use mrscraper_list_results to inspect individual results and mrscraper_get_proxy_bandwidth for proxy bandwidth.

Get the total proxy bandwidth used per proxy username within a date range, optionally limited to one region. Returns the usage list under the key array, with one entry per proxy username, each holding the username and its total bandwidth usage (username, total_bandwidth_usage) for the range as a number with no documented unit. Use this to see how much proxy traffic each proxy user consumed. Use mrscraper_get_analytic_statuses for scrape status counts and mrscraper_verify_api_token for token usage against the token limit. Requires an active MrScraper Proxy subscription: without one the API answers 403 with the message "You don't have an active Proxy subscription. Please subscribe to access this feature." No successful call was possible in testing, so the response shape comes from the vendor reference.

Get one scraping result by its id. Returns data, the result record: createdAt, id, userId, scraperId, type (for example AI or Bulk-AI), url, status, error, tokenUsage, runtime, bandwidthUsage, the extracted data (its shape depends on the scraper's agent and on whether the run was single or bulk), and the path fields dataPath and htmlPath, which were null in testing; only Scrape-Markdown records, and one markdown run that also took a screenshot, carried file paths inside data, as data_path and html_path. For a bulk job, the record's data holds mergedData, urlDetails and a summary with totalUrls, successfulUrls, failedUrls, scrapedCount, totalTokenUsage and estimatedFinishAt. Scraper API records carry a curl field that replays the request and contains the live x-api-token value, so never repeat or store curl (AI, rerun and bulk records have curl null); read status, type, url, tokenUsage and data instead. MrScraper also saves rejected calls as Finished records: one with tokenUsage 0 whose data holds only an error body (an error message with a traceId, or a single detail field) is a rejected call, not a result. Use this to read a single result, and to poll a bulk job, using the bulkResultId returned by mrscraper_bulk_rerun_ai_scraper or mrscraper_bulk_rerun_manual_scraper, until its status is Finished, Failed or Cancelled (Running means it is still going). Use mrscraper_list_results to browse many results. Requires the result id, found with mrscraper_list_results or, for a bulk job, the bulkResultId in a bulk rerun response. An unknown id answers 403 and a malformed id 400.

Render one web page in a real browser and capture a screenshot of its full scroll height or only the top viewport, with an optional full-page recording. Returns a JSON object whose screenshot field holds the base64-encoded image, with recording_path when record is true, alongside runtime, token_usage, error, residential_proxy_usage and the file paths html_path and data_path. No call returned an image in testing, so this shape comes from the vendor reference. Use this to see what the scraper saw, check a layout or archive a visual snapshot. Use mrscraper_scrape_html or mrscraper_scrape_markdown when you need the page content itself. Plan-token cost of a real screenshot was not observed: saved results from this tool showed 0 tokens in testing, apart from one mrscraper_scrape_markdown run with screenshot top that MrScraper filed as a screenshot (6 tokens). This tool always starts a real browser, and Scalekit ends every call after 10 seconds with a timeout error: 24 of 31 test calls timed out and none returned an image, so expect timeouts. mrscraper_scrape_markdown with screenshot set to top and super set to true returned an image inside the limit in testing (9.5 s, on the second attempt); the same call without super timed out. A proxy value that contains credentials was echoed back in the error text of a timed-out call in testing, so send only a proxy you can expose. An invalid URL answers 400 with message Invalid URL.

Ask AI to repair the saved workflow of a manual scraper after the target website changed its markup and the scraper started returning empty or partial data. Returns success, the scraperId and workflowUpdated according to the vendor reference, where workflowUpdated tells you whether the saved workflow was replaced. No manual scraper was available in testing, so only error responses were seen (422 for an AI scraper's id, 403 for an unknown id); the success response and what a failed repair leaves behind were not observed, so do not assume a failed repair leaves the workflow unchanged. Use this when mrscraper_rerun_manual_scraper or mrscraper_bulk_rerun_manual_scraper returns empty or partial data, and check workflowUpdated before rerunning. It changes the scraper's saved workflow rather than scraping a URL. Requires the scraperId of a manual scraper that already exists in the MrScraper account; this connector has no tool to create one. An AI scraper's id is answered with 422 'Self-heal is available only for manual scrapers'.

List scraping results for the account, with sorting, text search, an optional date-range filter and page-based pagination. Returns data, an array of result records (createdAt, id, userId, scraperId, type, url, status, error, tokenUsage, runtime, bandwidthUsage, the extracted data, and the path fields dataPath, htmlPath, recordingPath and screenshotPath, which were null in testing; only Scrape-Markdown records, and one markdown run that also took a screenshot, carried file paths inside data, as data_path and html_path), plus meta with page, pageSize, total and totalPage. Scraper API records carry a curl field that replays the request and contains the live x-api-token value, so never repeat or store curl (AI, rerun and bulk records have curl null); read status, type, url, tokenUsage and data instead. MrScraper also saves rejected calls as Finished records: one with tokenUsage 0 whose data holds only an error body (an error message with a traceId, or a single detail field) is a rejected call, not a result. Use this to browse or find results and their ids; the date range needs both startAt and endAt (a single bound was ignored in testing) and dateRangeColumn had no effect. Use mrscraper_get_result to read one result by id, including the progress of a bulk job.

Rerun an existing AI scraper against a URL. The vendor reference says reruns reuse cached results, which can reduce token usage and improve execution time; no saving was observed in testing. Returns the result record: result id, scraperId, type, url, status (Finished or Failed in testing), error, tokenUsage, runtime, bandwidthUsage, the extracted data (its shape depends on the scraper's agent: general, listing or map), html, markdown, screenshot, and the path fields htmlPath and dataPath, which were null in testing. If status is neither Finished nor Failed, read the same result id again with mrscraper_get_result. Use this for one URL at a time. Use mrscraper_bulk_rerun_ai_scraper to run the scraper on many URLs, mrscraper_rerun_manual_scraper for a manual scraper and mrscraper_create_ai_scraper to set up a new AI scraper. Per the vendor reference, the crawl settings (depth, pages, result limit and URL patterns) can be modified only for scrapers built with the map agent. On a map scraper in testing, maxPages, limit, includePatterns and excludePatterns each changed the crawl (maxPages 1 returned no URLs, ended Failed and still cost 1 plan token, limit 5 returned 5 URLs, a pattern filtered the URLs), while maxDepth 1 and 3 both returned 75 URLs with maxPages 3 (the creation run had returned 631 URLs for the same start page), so the page cap bounded the crawl and the effect of maxDepth was not isolated; give each pattern as one regular expression and combine several with alternation. Requires the scraperId of an AI scraper: read it from the scraperId field of the newest type-AI record in mrscraper_list_results, because mrscraper_create_ai_scraper normally times out in Scalekit before returning data.scraperId (that record appears only once creation finishes, 19 to 39 s after the call started). A single-URL rerun of a general scraper exceeded Scalekit's 10-second call limit in testing and returned a timeout error although MrScraper finished it (read it in mrscraper_list_results); prefer mrscraper_bulk_rerun_ai_scraper, which is asynchronous, for pages that may take long.

Rerun an existing manual (workflow) scraper against a URL. The vendor reference says reruns reuse cached results, which can reduce token usage and improve runtime; not observed in testing. Returns message and data. No manual scraper was available in testing, so only a failed call was seen: message 'Scraping operation error.' with data holding error, code, runtime, residential_proxy_usage and the paths data_path, html_path and recording_path, so check data.error. The vendor reference describes a result record with the extracted data on success. Use this for one URL at a time. Use mrscraper_bulk_rerun_manual_scraper to run the scraper on many URLs, mrscraper_rerun_ai_scraper for AI scrapers, and mrscraper_heal_manual_scraper when reruns start returning empty data because the target site changed its markup. Requires the scraperId of a manual scraper with a saved workflow that already exists in the MrScraper account; this connector has no tool to create one. An AI scraper's id is answered with 'The workflow is empty. Cannot rerun manual scraper without a workflow definition.'; sending a one-step extract workflow with an AI scraper's id returned the same answer in testing, so a manual scraper's saved workflow is needed.

Fetch the raw HTML of one web page in HTML mode (the tool always sends html=true), with optional Chromium rendering, real-device routing, geo-targeted proxies and waiting for a CSS selector. Returns the page's unparsed markup as a single text string in the result field; the response is text, not JSON. Use this for raw markup to feed your own parser or to audit meta tags and page structure. Use mrscraper_scrape_markdown for clean text, mrscraper_scrape_json for structured fields from a prompt, mrscraper_get_screenshot for an image, and mrscraper_scrape_sitemap to discover URLs first. Each call consumes MrScraper plan tokens and is saved as a result record (this tool has no saveResult input). Scalekit ends every call after 10 seconds, whatever timeout says, and returns a timeout error; every html call finished inside that limit in testing, including calls with browser rendering. An invalid URL answers 400, and a target page that returns 404 comes back as an error.

Extract structured JSON from a single web page by describing the data you want in a natural-language prompt, using the general AI agent (the tool always sends agent general). Returns a JSON object whose data field holds the extracted structure, alongside success, status, error, runtime, token_usage and thread_id; the html, markdown and screenshot fields were empty in the responses seen in testing. A scrape that fails (invalid URL, target page returned 404) still returns HTTP 200, with success false and status 'Could not complete the request', so check success before using data; what the error field holds on such failures was not recorded in testing. Use this for one page, such as a product, article or profile. Use mrscraper_scrape_listing_page for multi-page catalogs and search results, mrscraper_scrape_markdown for plain page text, and mrscraper_create_ai_scraper to create a scraper you can rerun later. Per the vendor reference, the prompt only parses the scraped content and cannot instruct the scraper itself, and a section starting with 'Json Schema:' appended to it shapes the output (not tested here). Each call consumes MrScraper plan tokens. Scalekit ends every call after 10 seconds and returns a timeout error; successful calls took about 7 to 10 seconds on small pages and about half of the matrix calls timed out, and a timed-out scrape may be saved a little later, so check mrscraper_list_results before retrying.

Extract the repeating items from a paginated listing, catalog grid or search results across multiple pages in one run, using the listing AI agent with super mode on (the tool always sends agent listing and super=true). Returns a JSON object whose data field is keyed by page, each entry giving the page number and the items extracted from that page (shape from the vendor reference; no listing run completed in testing), alongside success, status, error, runtime and token_usage. A scrape that fails (for example an invalid URL) still returns HTTP 200, with success false and an empty data field, so check success before using data. Per the vendor reference this handles numbered pagination, Load More buttons and infinite scroll, up to maxPages pages (documented default 3); none of this was observed because no listing run completed in testing. Use mrscraper_scrape_json for a single page, mrscraper_scrape_sitemap to discover URLs instead of extracting items, and mrscraper_scrape_html for raw markup. The tool always sends super mode, which the vendor reference lists as required for this endpoint. Each call consumes MrScraper plan tokens. Scalekit ends every call after 10 seconds and returns a timeout error; in testing every real listing call timed out, even a one-page listing, and no saved result for a real page was found afterwards, so expect timeouts here.

Convert one web page into Markdown in Markdown mode (the tool always sends markdown=true); on one test page the output was 81% smaller than the raw HTML, dropped the script tags and kept headings, list items and links. Returns a JSON object whose markdown field holds the page as Markdown, alongside runtime, token_usage, error, residential_proxy_usage and the file paths html_path and data_path. The html field comes back empty, screenshot holds a base64 image only when screenshot is set, and returned cookies appear in data.cookies. Use this for token-efficient page text for prompts, RAG pipelines and document stores. Use mrscraper_scrape_html for raw markup, mrscraper_scrape_json for structured fields extracted by a prompt, and mrscraper_scrape_listing_page for multi-page catalogs. Each call consumes MrScraper plan tokens, and the result is saved to the Result tab unless saveResult is false. Scalekit ends every call after 10 seconds and returns a timeout error; in testing calls with super true finished far more often than calls without it, so set super to true to finish inside the limit, and a timed-out scrape may be saved a little later, so check mrscraper_list_results before retrying. A proxy value that contains credentials was echoed back in the error text of a timed-out mrscraper_get_screenshot call, and the same transport error applies here, so send only a proxy you can expose. An invalid URL answers 400 with detail Bad URL.

Crawl a site's link structure from a starting URL and collect the URLs it discovers, using the map AI agent (the tool always sends agent map). Returns a JSON object whose data field holds a count and the list of discovered URLs (urls), without downloading full page content, alongside success, status, runtime and token_usage. Use this to map site architecture or build seed URL lists before bulk extraction with mrscraper_scrape_json, mrscraper_scrape_markdown or mrscraper_scrape_html. Use mrscraper_scrape_listing_page to extract items from a listing rather than URLs. Per the vendor reference the crawl is bounded by maxDepth (default 2), maxPages (default 3) and limit (default 1000), and scoped with includePatterns and excludePatterns, each a single regular expression (combine several with alternation: include patterns separated by a newline or a comma matched nothing, and exclude patterns separated by a newline excluded nothing in testing). In testing maxPages and limit changed the output, while maxDepth 1 and 3 returned the same 47 URLs at maxPages 3, so the page cap bounded the crawl and the effect of maxDepth was not isolated. Each call consumes MrScraper plan tokens. Scalekit ends every call after 10 seconds and returns a timeout error. In testing maxPages 1 found no URLs in any of 38 saved results, and maxPages 3 found up to 47 URLs on a small site with MrScraper runtimes of 7.1 to 9.2 s (15 saved results), close to the limit, with some calls timing out, so expect timeouts on larger sites. A timed-out crawl may be saved a little later, so check mrscraper_list_results before retrying. An invalid URL answers a bare Internal Server Error.

Verify the connected MrScraper API token and fetch the subscription account it belongs to. Returns the subscription account: its id, the owning user id (userId), plan details (subscriptionItem), status (stripeStatus), billing period (currentPeriodStart, currentPeriodEnd, endsAt, cancelAtPeriodEnd, isAutoRenew), token limit and usage (tokenLimit, tokenUsage), concurrency and rate limits (maxConcurrency, rateLimit, rateTtl), and a user object with the owner's profile (name, email, Google and Stripe ids, team). The user object is personal account data, so never repeat it in output and read only tokenLimit and tokenUsage for budget checks. The vendor docs example also shows a latestApiToken field that the live API did not return when checked; treat it as a secret if it ever appears. Use this to compare token usage against the token limit or as a quick auth check, since a 401 Unauthorized response means the token is missing or invalid. Use mrscraper_get_proxy_bandwidth for proxy usage and mrscraper_get_analytic_statuses for scrape status counts.