MCP Server

MrScraper MCP connects Model Context Protocol clients to the MrScraper web-data service. It exposes seven tools:

Use the hosted Streamable HTTP endpoint for a managed connection, or run the published MCP package locally through Streamable HTTP or stdio.

Capabilities

Requirements

• A MrScraper account
• An MCP client with Streamable HTTP support
• An API key only when the client cannot use OAuth 2.1 or when running the server locally

Quick start with the hosted server

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp"
    }
  }
}

Copyable AI setup prompt

Connect MrScraper MCP to this agent. Detect the current MCP client and use its native Streamable HTTP setup to add a server named mrscraper at exactly https://mcp.mrscraper.com/mcp with no static credential. Complete the OAuth 2.1 browser sign-in; if it does not start automatically, use the client's MCP login or authenticate command. Only if the client does not support OAuth, fall back to a MrScraper API key from https://app.mrscraper.com/api-tokens stored through the client's environment-variable or secret-storage mechanism and sent as Authorization: Bearer <key>. Reload the MCP client when required, then list the tools and confirm that fetch, scrape, serp, status, rerun, results, and result are available.

Client configuration

Add the hosted URL without a static Authorization header, then complete browser sign-in when the client prompts you.

Codex

codex mcp add mrscraper \
  --url https://mcp.mrscraper.com/mcp

Codex uses OAuth by default for Streamable HTTP servers. If browser sign-in does not start automatically, run codex mcp login mrscraper.

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  mrscraper https://mcp.mrscraper.com/mcp

Open /mcp inside Claude Code and authenticate, or run claude mcp login mrscraper from your shell.

Claude and Claude Desktop

Cursor

Open Cursor Settings → Tools & MCP → Add Custom MCP, then add:

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp"
    }
  }
}

Refresh the MCP server list, then authenticate when prompted.

VS Code

Add the server to your user settings:

{
  "mcp": {
    "servers": {
      "mrscraper": {
        "type": "http",
        "url": "https://mcp.mrscraper.com/mcp"
      }
    }
  }
}

For a workspace configuration, place the server object under servers in .vscode/mcp.json. Start the server and VS Code opens a browser for OAuth.

Windsurf

Add the following entry to the Windsurf MCP configuration:

{
  "mcpServers": {
    "mrscraper": {
      "serverUrl": "https://mcp.mrscraper.com/mcp"
    }
  }
}

Refresh the MCP server list, then complete OAuth when prompted.

Other MCP clients

Use these connection values:

API key fallback

If a client cannot complete OAuth, create an API key, store it through the client's secret mechanism, and send it as a bearer token:

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

For Codex, pass the environment-variable name instead of embedding the key:

export MRSCRAPER_API_KEY="YOUR_MRSCRAPER_API_KEY"
codex mcp add mrscraper \
  --url https://mcp.mrscraper.com/mcp \
  --bearer-token-env-var MRSCRAPER_API_KEY

Authentication

The hosted server publishes OAuth 2.1 protected-resource metadata and challenges unauthenticated clients to start browser sign-in. Access tokens are issued for the exact https://mcp.mrscraper.com/mcp resource and use scrape:read, scrape:write, and account:read scopes. A tool called without its required scope returns 403 insufficient_scope.

API keys remain supported for clients without OAuth and carry full account authority. Authentication stays at the transport layer; tools never accept credentials as arguments.

Run the MCP server locally

Node.js 20 or newer is required.

Published package over stdio

{
  "mcpServers": {
    "mrscraper": {
      "command": "npx",
      "args": ["-y", "@mrscraper/mcp@latest"],
      "env": {
        "MRSCRAPER_API_KEY": "YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

Source checkout over Streamable HTTP

git clone https://github.com/mrscraper-com/mrscraper-mcp.git
cd mrscraper-mcp
npm ci
npm run build

TRANSPORT=http npm start

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

Docker

docker build -f docker/Dockerfile -t mrscraper-mcp .
docker run --rm -p 8000:8000 mrscraper-mcp

The image binds to `0.0.0.0). Apply network controls appropriate for the deployment and keep bearer verification enabled.

Environment variables

Security behavior

• HTTP authentication is enabled by default.
• Credential-bearing response headers are filtered from tool output.
• Parsed JSON credential metadata and credentials in generated curl commands are redacted.
• Extracted scraper values remain available in the response's data field.
• Browser-origin requests are accepted from trusted local origins and exact values configured through MRSCRAPER_ALLOWED_ORIGINS.
• Tool calls receive the caller's authenticated OAuth token or API key through the MCP transport rather than through tool arguments.

Choosing the right tool

A discovery workflow commonly uses serp first, followed by fetch for the page response or scrape for defined output fields. A saved-scraper workflow commonly uses scrape, then rerun, followed by result.

Common response envelope

API-backed tools return the same envelope through MCP structuredContent and a formatted JSON text block:

{
  "status_code": 200,
  "data": {},
  "headers": {
    "content-type": "application/json"
  }
}

API failures preserve the envelope in structuredContent and set the MCP result's isError flag. Input-contract errors are returned as MCP tool errors. This lets clients inspect status, response data, and safe headers while also following the standard MCP error signal.

Tool reference

fetch

Use fetch for a known URL when you need the page response from MrScraper Web Unblocker. Each invocation corresponds to one request:

GET https://api.mrscraper.com/

Basic request

{
  "url": "https://example.com/products"
}

JavaScript-rendered page

{
  "url": "https://example.com/products",
  "browser_rendering": true,
  "wait_for_selector": ".product-card",
  "timeout": 45
}

Geo-sensitive page

{
  "url": "https://example.com/offers",
  "browser_rendering": true,
  "geo_code": "ID",
  "home_page": true,
  "block_resources": true,
  "max_retries": 3,
  "token_cap": 20
}

Parameters

The response body is available in the envelope's data field, commonly as HTML. Start with the basic request, then select browser and loading controls that match the target page.

scrape

Use scrape when you need defined fields, repeated records, or a site URL map. It calls:

POST https://api.app.mrscraper.com/api/v1/scrapers-ai

Agent modes

Choose inputs from the selected agent's row. The default agent is general.

General extraction

{
  "url": "https://example.com/product",
  "agent": "general",
  "prompt": "Extract the product name, price, availability, description, and image URLs",
  "proxy_country": "US"
}

The request body includes url, message, and agent, plus proxyCountry when supplied.

Listing extraction

{
  "url": "https://example.com/products",
  "agent": "listing",
  "prompt": "Extract every product name, price, availability, and detail URL",
  "max_pages": 5
}

Listing requests are synchronous. Use max_pages to define the desired page scope. When it is omitted, the service applies its configured default.

Site map

{
  "url": "https://example.com",
  "agent": "map",
  "max_depth": 2,
  "max_pages": 50,
  "limit": 1000,
  "include_patterns": "/products/",
  "exclude_patterns": "/cart/|/checkout/"
}

Map requests send url, agent, and the crawl controls supplied in the tool call. Omitted crawl controls use service defaults.

Best-effort schema guidance

{
  "url": "https://example.com/product",
  "prompt": "Extract the product",
  "schema_prompt": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "in_stock": { "type": "boolean" }
    },
    "required": ["name", "price"]
  }
}

The MCP server appends schema_prompt to the natural-language instruction as shape guidance. Validate the returned value in the consuming application when strict conformance is required.

Parameters

Reproduce a scrape with rerun

Every successful scrape creates a saved AI scraper configuration by default. The response run object contains scraperId. Pass that UUID to rerun as scraper_id to apply the same saved prompt and agent configuration to the original URL or another URL:

{
  "target": "https://example.com/product-2",
  "type": "ai",
  "scraper_id": "scraper-uuid"
}

This makes the scraper configuration reproducible, but page changes and model behavior can still change the extracted values.

rerun also supports dashboard-built manual workflows and asynchronous bulk jobs across multiple target URLs. See the full rerun section below for the available modes and result-tracking workflow.

serp

Use serp when discovery starts from a Google query or Google search URL. It calls:

POST https://sync.scraper.mrscraper.com/api/google/serp/v2/sync

Search query

{
  "query_or_url": "iphone 17",
  "region": "id",
  "language": "id",
  "page": 2,
  "format": "json",
  "render_js": false
}

Google search URL

{
  "query_or_url": "https://www.google.com/search?q=iphone+17&gl=us&hl=en&start=20"
}

For a Google URL, the server derives:

Explicit region, language, and page inputs take priority over the corresponding URL values.

Parameters

status

Use status for account information and optional domain request outcomes. Every call reads:

GET https://api.app.mrscraper.com/api/v1/subscription-accounts

Supplying domain adds:

GET https://api.app.mrscraper.com/api/v1/analytic/statuses

Account status

{}

Domain analytics

{
  "domain": "https://www.example.com/products",
  "from": "7d",
  "to": "now",
  "action": "fetch",
  "api_token_name": "production"
}

The domain input accepts a hostname or a URL. URLs are normalized to their hostname before the analytics request.

Date syntax

Parameters

Status summary

{
  "kind": "mrscraper-cli-status-summary",
  "source_endpoints": [
    "/subscription-accounts",
    "/analytic/statuses"
  ],
  "status_code": 200,
  "data": {
    "account": {
      "subscription_status": "active",
      "enterprise": false,
      "token_usage": 250,
      "token_limit": 1000,
      "token_remaining": 750,
      "usage_percent": 25,
      "rate_limit": 10,
      "rate_ttl": 60,
      "auto_renew": true,
      "ends_at": null,
      "user": {
        "name": "Ada",
        "email": "ada@example.com",
        "verified": true
      }
    },
    "analytics": {
      "domain": "www.example.com",
      "from": "2026-08-11 12:00:00 UTC",
      "to": "2026-08-18 12:00:00 UTC"
    }
  }
}

The summary selects account fields, calculates token_remaining and usage_percent, and records every source endpoint used for the response. When domain analytics encounter an API failure, the account summary remains in data.account and the analytics response is available in data.analytics.

rerun

Use rerun with the UUID of an existing scraper. Choose its type and target count independently:

• Set type to ai for an AI scraper created by the scrape tool.
• Set type to manual for a step-based workflow created in the MrScraper dashboard. MCP reruns existing manual workflows; it does not create them.
• Leave bulk as false for one URL. Set it to true to submit the same saved configuration once with a comma- or newline-separated URL list.

Manual reruns can be single or bulk. Bulk reruns can use either an AI or a manual scraper; bulk describes the number of targets, not the scraper type. Bulk mode submits one asynchronous backend job instead of repeating the single-URL tool call locally. Save data.data.bulkResultId from the response and pass it to result as result_id until the stored result is finished.

The combination of type and bulk selects one endpoint:

The endpoint paths above use the platform API base:

https://api.app.mrscraper.com/api/v1

Single AI rerun

{
  "target": "https://example.com/products",
  "type": "ai",
  "scraper_id": "scraper-uuid",
  "max_depth": 2,
  "max_pages": 50,
  "limit": 1000,
  "include_patterns": "/products/",
  "exclude_patterns": "/cart/|/checkout/"
}

Single manual rerun

{
  "target": "https://example.com/product/123",
  "type": "manual",
  "scraper_id": "scraper-uuid"
}

Bulk AI rerun

{
  "target": "https://example.com/a,https://example.com/b\nhttps://example.com/c",
  "type": "ai",
  "bulk": true,
  "id": "scraper-uuid"
}

The bulk target parser separates URLs on commas and newlines.

Parameters

Manual reruns carry a compliance acknowledgment in the MCP server instructions. MCP clients should present that acknowledgment before executing a manual rerun.

results

Use results to browse stored runs through:

GET https://api.app.mrscraper.com/api/v1/results

Paginated request

{
  "sort_field": "updatedAt",
  "sort_order": "desc",
  "page_size": 25,
  "page": 1
}

Filtered request

{
  "sort_field": "updatedAt",
  "sort_order": "asc",
  "page_size": 50,
  "page": 1,
  "search": "example.com",
  "date_range_column": "updatedAt",
  "start_at": "2026-08-01T00:00:00Z",
  "end_at": "2026-08-18T23:59:59Z"
}

Parameters

The results API receives the sort_field value supplied by the caller. sort_order is normalized and sent as ASC or DESC.

result

Use result when the result UUID is already known:

GET https://api.app.mrscraper.com/api/v1/results/{result_id}

{
  "result_id": "result-uuid"
}

Troubleshooting