MrScraper MCP

MrScraper MCP Server for Web Scraping and Web Search

MrScraper MCP is the official MrScraper server for the Model Context Protocol. It connects AI assistants to page content and web search through two tools, plus an account check. Retrieve HTML, Markdown, or screenshots with scraperAPI, discover pages with webSearch, and check your plan and token usage with status.

Use the hosted server with OAuth sign-in, or run the open-source server locally with the @mrscraper/mcp npm package. See the MrScraper MCP documentation for setup instructions and client configurations.

The server exposes three tools:

scraperAPI  webSearch  status

Deployment options

The hosted server signs you in through your browser with OAuth 2.1, so there is no key to copy. Self-hosted and stdio setups use a MrScraper API key from app.mrscraper.com/api-tokens, which the hosted server also still accepts.

ChatGPT and Codex connect to https://mcp.mrscraper.com/mcp/chatgpt, which uses the same sign-in and tools with fewer scraperAPI options (see ChatGPT and Codex endpoint).

Connect to the hosted server

Point your MCP client at https://mcp.mrscraper.com/mcp with no credential. The server answers with an OAuth challenge, your client opens a browser, and you approve the connection on app.mrscraper.com.

claude mcp add --transport http --scope user \

mrscraper https://mcp.mrscraper.com/mcp

For clients configured by file, omit the headers block entirely:

{

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

Use exactly this URL, including the /mcp path. It is the resource identifier access tokens are issued for, and a token minted for a different spelling of the address will be refused.

What you are approving

A tool called without its scope is refused with 403 insufficient_scope, and your client will offer to grant the missing permission.

scraperAPI submits a scraping job to the backend with POST /, which requires scrape:write. Connections authorized before this scope was advertised need to authorize again and grant it; scrape:read alone does not grant write access.

Disconnect it later under Connected applications in your MrScraper account. Disconnecting revokes the refresh tokens immediately; an access token already issued stops working within the hour.

Connect with an API key instead

An API key still works as a bearer token, which is what self-hosted deployments and non-OAuth clients use:

{

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

Use your client's environment-variable or secret-storage feature so the key stays out of project files. An API key carries your full account authority, so no scope is enforced against it.

Codex

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

Start Codex from an environment containing MRSCRAPER_API_KEY. Codex stores the environment-variable name in its MCP configuration.

Claude Code

claude mcp add \

--transport http \ --scope user \ --header "Authorization: Bearer YOUR_MRSCRAPER_API_KEY" \ mrscraper https://mcp.mrscraper.com/mcp

Claude Code also supports project and local scopes. Choose the scope that matches how broadly the connection should be available.

Copyable agent setup prompt

Connect MrScraper MCP to this agent. Detect the current MCP client and configure a Streamable HTTP server named mrscraper at https://mcp.mrscraper.com/mcp with no credential. The server uses OAuth 2.1, so the client will open a browser to sign in. If the client cannot do 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 the only available tools.

Choosing a tool

A discovery workflow is webSearch → scraperAPI. Both web tools advertise readOnlyHint: true, openWorldHint: true, and destructiveHint: false; status is read-only and not open-world. Authentication comes from the MCP connection; no tool takes an API token argument.

Migration from the previous tool set

Only scraperAPI, webSearch, and status are registered. The other old tool names are removed.

super_mode becomes super. home_page now maps to warmStart, and token_cap=0 is accepted. Restart the server and reconnect the MCP client after updating so it refreshes tools/list.

Changes in 0.4.0

The HTTP server adds a second endpoint, /mcp/chatgpt, for the MrScraper plugin in ChatGPT and Codex. It is described under ChatGPT and Codex endpoint. /mcp is unchanged.

Changes in 0.3.0

webSearch now calls MrScraper's web search action on the Scraper API host and returns a ranked list of results. It gained num_results, and region must be a two-letter country code. The 0.2 options raw, format, language, page, and render_js are no longer supported: calls that still send them succeed, and the options are ignored. MRSCRAPER_SYNC_BASE_URL is gone; MRSCRAPER_FETCH_BASE_URL now covers both web tools.

Tool reference

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

scraperAPI

POST https://api.mrscraper.com/

Start with a known URL:

{

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

Request HTML, Markdown, and a screenshot together:

{

"url": "https://example.com", "html": true, "markdown": true, "screenshot": true, "super": true, "home_page": true, "geo_code": "ID", "timeout": 120 }

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

The JSON body contains url, maxRetries, and optional tokenCap. Page options are query parameters. For API keys, the request also includes the SDK-compatible token query parameter and Authorization/x-api-token headers. OAuth JWTs are sent only through Authorization.

webSearch