MCP Server

MrScraper MCP is the official Model Context Protocol server for MrScraper. It connects AI clients to web page retrieval, web search, and your account usage.

MrScraper MCP server source code on GitHub · Install the @mrscraper/mcp npm package

The server exposes three 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 scraperAPI, webSearch, and status 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.

To add MrScraper's three skills for page retrieval and web search along with the server, install the MrScraper plugin for Claude Code instead:

claude plugin marketplace add mrscraper-com/mrscraper-claude-plugin
claude plugin install mrscraper@mrscraper-claude

The plugin is also listed on ClaudePluginHub.

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. A tool called without its required scope returns 403 insufficient_scope, and your client can offer to grant the missing permission.

API keys remain supported for clients without OAuth and carry full account authority, so no scope is enforced against them. 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 is redacted, and network errors redact signed query credentials.
• status copies only account usage fields, so the API key and billing identifiers in the account record never reach the client.
• Browser-origin requests are accepted from trusted local origins, from claude.ai and chatgpt.com, and from 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 webSearch first, followed by scraperAPI for the pages that will inform the answer. Agents produce summaries, tables, and structured output from the retrieved content.

Migration from the previous tool set

Reconnect the MCP client after the change so it refreshes its tool list.

In 0.3.0, webSearch dropped the raw, format, language, page, and render_js options because the new web search endpoint doesn't support them; calls that still send them succeed and the options are ignored. It added num_results.

Common response envelope

scraperAPI and webSearch 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. status returns the account summary described in its reference.

Tool reference

The options and defaults of scraperAPI follow the Python SDK's scraper_api method. Tool names use camel case; argument names use snake case.

scraperAPI

Use scraperAPI for a known URL. It calls:

POST https://api.mrscraper.com/

The JSON body contains url, maxRetries, and optional tokenCap. Page options are sent as query parameters.

Basic request

{
  "url": "https://www.scrapethissite.com/pages/simple/"
}

HTML, Markdown, and a screenshot

{
  "url": "https://www.scrapethissite.com/pages/simple/",
  "html": true,
  "markdown": true,
  "screenshot": true
}

Real-device routing from another country

{
  "url": "https://www.scrapethissite.com/pages/simple/",
  "super": true,
  "geo_code": "ID",
  "home_page": true
}

Omit browser_rendering, or set it to null, to let the service try without a browser and fall back to browser loading when needed. true forces browser loading and false disables it. A screenshot always forces browser loading. super selects real-device routing independently of browser rendering.

Response

The page content is in data:

{
  "status_code": 200,
  "data": {
    "html": "<!DOCTYPE html>...",
    "markdown": "...",
    "screenshot": "/9j/4AAQSkZJRgABAQAAAQAB...",
    "token_usage": 3,
    "runtime": 18.02,
    "retry_count": 0,
    "error": null
  },
  "headers": {
    "content-type": "application/json",
    "x-status-code": "200",
    "token_usage": "3"
  }
}

screenshot is a base64-encoded JPEG and can be large. x-status-code is the target page's status. Usage is calculated from runtime and bandwidth: one plan token per 30 seconds and one plan token per 0.25 MB, rounded up per component.

Parameters

webSearch

Use webSearch when no target URL is known. It calls MrScraper's web search action on the Scraper API host:

POST https://api.mrscraper.com

The request body carries action: "websearch", the query, and the optional country and result count. This asks for 20 results from the United Kingdom:

{
  "url": "running shoes",
  "region": "gb",
  "num_results": 20
}

A search results URL also works as url; its q parameter becomes the query.

Results

The results are a ranked list in data.data:

{
  "status_code": 200,
  "data": {
    "success": true,
    "message": "Search completed",
    "data": [
      {
        "rank": 1,
        "title": "Web Scraping API | MrScraper",
        "url": "https://mrscraper.com/",
        "description": "Extract structured data from any website with AI.",
        "source": "MrScraper"
      }
    ],
    "tokenUsage": 1
  },
  "headers": {
    "content-type": "application/json; charset=utf-8"
  }
}

Parameters

status

Use status to check the connected account. It takes no input and calls:

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

Status summary

{
  "kind": "mrscraper-cli-status-summary",
  "source_endpoints": ["/subscription-accounts"],
  "status_code": 200,
  "data": {
    "account": {
      "subscription_status": "active",
      "enterprise": false,
      "token_usage": 61240,
      "token_limit": 100000,
      "token_remaining": 38760,
      "usage_percent": 61.24,
      "rate_limit": 0,
      "rate_ttl": 0,
      "auto_renew": true,
      "ends_at": "2026-12-01T00:00:00.000Z",
      "user": {
        "name": "Ada",
        "email": "ada@example.com",
        "verified": true
      }
    }
  }
}

The summary selects account fields and calculates token_remaining and usage_percent. An OAuth connection needs the account:read scope.

Troubleshooting