Skip to main content
Glama
ScrapeOps

ScrapeOps MCP Server

by ScrapeOps

ScrapeOps MCP Server

A Model Context Protocol (MCP) server that exposes the full capabilities of the ScrapeOps Proxy API to LLM clients (Cursor, Claude Desktop, VS Code). Enable AI agents to browse the web, bypass anti-bots, render JavaScript, take screenshots, and perform structured data extraction autonomously.

Features

  • 🌐 Web Browsing - Browse any webpage with proxy support

  • 🌍 Geo-Targeting - Access websites from 12+ countries

  • 🏠 Residential/Mobile Proxies - Higher success rates on challenging sites

  • πŸ€– Anti-Bot Bypass - Multiple bypass levels (Cloudflare, DataDome, PerimeterX, etc.)

  • πŸ–ΌοΈ Screenshots - Capture visual snapshots of pages

  • ⚑ JavaScript Rendering - Full headless browser capabilities

  • πŸ“Š Structured Extraction - LLM-powered data extraction with schemas

  • πŸ”„ Auto-Extract - Domain-specific parsers for popular sites

Related MCP server: Spider MCP Server

Installation

Running with npx

env SCRAPEOPS_API_KEY=YOUR_API_KEY npx -y @scrapeops/mcp

Manual Installation

npm install -g @scrapeops/mcp

Configuration

Environment Variables

Variable

Required

Description

SCRAPEOPS_API_KEY

Yes

Your ScrapeOps API key from scrapeops.io

How It Works

The MCP server uses a simple, single-request approach:

  1. Basic Request: If no options are specified, a basic request is made (URL only)

  2. User-Specified Options: If options like render_js, residential, or premium are specified, they are used directly

  3. On Failure: Returns helpful error with suggestions - the AI/user decides what to do next

  4. No Auto-Retry: The server does not automatically retry with different options - this gives you full control

Example Flow:

  • You ask: "Scrape https://example.com"

  • Server makes basic request (no extra params)

  • If it fails (403), returns error with suggestions: "Try with residential: true"

  • You decide: "OK, scrape it with residential proxy"

  • Server makes request with residential: true

Running on Cursor

  1. Open Cursor Settings

  2. Go to Features > MCP Servers

  3. Click "+ Add new global MCP server"

  4. Enter the following configuration:

{
  "mcpServers": {
    "@scrapeops/mcp": {
      "command": "npx",
      "args": ["-y", "@scrapeops/mcp"],
      "env": {
        "SCRAPEOPS_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

Running on Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "@scrapeops/mcp": {
      "command": "npx",
      "args": ["-y", "@scrapeops/mcp"],
      "env": {
        "SCRAPEOPS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Running on VS Code

Add to your User Settings (JSON) via Ctrl + Shift + P β†’ Preferences: Open User Settings (JSON):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "ScrapeOps API Key",
        "password": true
      }
    ],
    "servers": {
      "scrapeops": {
        "command": "npx",
        "args": ["-y", "@scrapeops/mcp"],
        "env": {
          "SCRAPEOPS_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Running on Windsurf

Add to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "@scrapeops/mcp": {
      "command": "npx",
      "args": ["-y", "@scrapeops/mcp"],
      "env": {
        "SCRAPEOPS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Running Local Server (HTTP/SSE Transport)

You can run the server locally as an HTTP/SSE server instead of using stdio transport. This is useful for development or custom deployments.

1. Start the server:

# Set the port for HTTP/SSE mode (required for local server)
export PORT=8080
export SCRAPEOPS_API_KEY=your-api-key-here

# Run the server
npm start
# or if you have the package installed globally
scrapeops-mcp

The server will start on http://localhost:8080/sse (or the port specified by the PORT environment variable).

Note: If PORT is not set, the server will run in stdio mode (for use with npx in MCP clients like Cursor). Set PORT explicitly to run as an HTTP/SSE server.

2. Configure Cursor to connect to the local server:

Edit your Cursor MCP configuration file (typically at ~/.cursor/mcp.json or in Cursor Settings):

{
  "mcpServers": {
    "@scrapeops/mcp": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "scrapeops-api-key": "your-api-key-here"
      }
    }
  }
}

Note: When using HTTP/SSE transport, you can pass the API key either:

  • Via the scrapeops-api-key header in the configuration (as shown above), or

  • Via the SCRAPEOPS_API_KEY environment variable when starting the server

Available Tools

Tool 1: maps_web

General-purpose web browsing tool for reading pages, taking screenshots, and bypassing anti-bot protections.

Usage Examples:

// Simple page browse
{
  "name": "maps_web",
  "arguments": {
    "url": "https://example.com"
  }
}

// Screenshot from Germany with residential proxy
{
  "name": "maps_web",
  "arguments": {
    "url": "https://example.de",
    "country": "de",
    "residential": true,
    "screenshot": true
  }
}

// Bypass Cloudflare protection
{
  "name": "maps_web",
  "arguments": {
    "url": "https://protected-site.com",
    "bypass_level": "cloudflare_level_2",
    "residential": true,
    "render_js": true
  }
}

Tool 2: extract_data

Structured data extraction using auto-parsing or LLM-powered extraction.

Usage Examples:

// Auto-extract from known domain
{
  "name": "extract_data",
  "arguments": {
    "url": "https://www.amazon.com/dp/B09V3KXJPB",
    "mode": "auto"
  }
}

// LLM extraction for product page
{
  "name": "extract_data",
  "arguments": {
    "url": "https://shop.example.com/product/123",
    "mode": "llm",
    "data_schema": "product_page",
    "response_format": "json"
  }
}

// Extract job listings with anti-bot bypass
{
  "name": "extract_data",
  "arguments": {
    "url": "https://careers.example.com/jobs",
    "mode": "llm",
    "data_schema": "job_search_page",
    "bypass_level": "generic_level_2",
    "render_js": true
  }
}

User Stories

The Visual Debugger

"User complains a site looks broken in Germany. The AI calls maps_web(url='...', country='de', screenshot=true). The user sees the actual screenshot of the site rendered via a German residential IP."

The Efficient Scraper

"User needs pricing data. Instead of fetching HTML and parsing it (wasting tokens), the AI calls extract_data(url='...', mode='llm', data_schema='product_page'). ScrapeOps handles the heavy lifting, and the AI just displays the final JSON."

The Bypass Expert

"The AI tries to access a site and gets blocked. It automatically retries the request using maps_web with bypass_level='generic_level_3' and residential=true to overcome the blockage."

System Configuration

The server includes configurable retry parameters with exponential backoff:

const RETRY_CONFIG = {
  maxAttempts: 1,      
  initialDelay: 1000, 
};

Retry Behavior:

  • Network errors are retried once regardless of maxAttempts setting

  • To enable retries, set SCRAPEOPS_RETRY_MAX_ATTEMPTS environment variable

Custom Configuration Example:

# Enable retries with 3 attempts
export SCRAPEOPS_RETRY_MAX_ATTEMPTS=3
export SCRAPEOPS_RETRY_INITIAL_DELAY=1000

Error Handling

Status Code

Error

Resolution

401

Invalid API Key

Check your SCRAPEOPS_API_KEY environment variable

403

Forbidden

Target website blocking request - consider using advanced parameters

404

Not Found

Verify the URL is correct

429

Rate Limited

Too many requests - wait before retrying (NOT auto-retried)

500

Server Error

Automatically retried up to 3 times with exponential backoff

502/503

Gateway/Service Error

Temporary issue - NOT auto-retried

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio transport)
SCRAPEOPS_API_KEY=your-key npm start

# Run tests
npm test

API Reference

Base URL: https://proxy.scrapeops.io/v1/

Authentication: Query parameter ?api_key=... (managed via server-side environment variables)

For full API documentation, visit ScrapeOps Documentation.

License

MIT License - see LICENSE file for details.

Support

Available Tools

3 tools
extract_dataA

Extract structured data from webpages using auto-parsing or LLM-powered extraction.

Best for:

  • Getting product information (prices, names, descriptions)

  • Extracting job listings data

  • Parsing search results

  • Collecting structured company information

  • Real estate listings extraction

Extraction Modes:

  • auto: Domain-specific parsers for common sites (Amazon, Google, etc.)

  • llm: AI-powered extraction with customizable schemas

Data Schemas (for LLM mode):

  • Product: product_page, product_reviews_page, product_search_page, product_seller_page

  • Jobs: job_page, job_advert_page, job_search_page

  • Company: company_page, company_job_page, company_review_page, company_search_page

  • Real Estate: real_estate_page, real_estate_profile_page, real_estate_search_page

  • Search: serp_search_page

Usage Examples:

  1. Auto-extract from known domain:

{
  "name": "extract_data",
  "arguments": {
    "url": "https://www.amazon.com/dp/B09V3KXJPB",
    "mode": "auto"
  }
}
  1. LLM extraction for product page:

{
  "name": "extract_data",
  "arguments": {
    "url": "https://shop.example.com/product/123",
    "mode": "llm",
    "data_schema": "product_page",
    "response_format": "json"
  }
}
  1. Extract job listings with anti-bot bypass:

{
  "name": "extract_data",
  "arguments": {
    "url": "https://careers.example.com/jobs",
    "mode": "llm",
    "data_schema": "job_search_page",
    "bypass_level": "generic_level_2",
    "render_js": true
  }
}
  1. Extract real estate data in markdown:

{
  "name": "extract_data",
  "arguments": {
    "url": "https://realestate.example.com/listing/456",
    "mode": "llm",
    "data_schema": "real_estate_page",
    "response_format": "markdown"
  }
}

Returns: Structured JSON or Markdown data extracted from the page.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
modeYes
waitNo
mobileNo
countryNo
premiumNo
wait_forNo
render_jsNo
data_schemaNo
device_typeNo
residentialNo
bypass_levelNo
keep_headersNo
session_numberNo
response_formatYesjson
follow_redirectsNo
max_request_costNo
optimize_requestNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden and discloses extraction modes, data schemas, anti-bypass options, and return format. However, it omits behaviors for many parameters like wait, mobile, and follow_redirects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections and examples, front-loading the purpose. It is appropriately sized but could be slightly trimmed without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 18 parameters and no output schema, the description covers core functionality well but lacks details on many optional parameters and error/rate-limit behaviors. It is complete for basic usage but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description compensates by explaining key parameters (url, mode, data_schema, bypass_level) via examples. But many parameters (e.g., wait, country, session_number) remain unexplained, making it only partially helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts structured data from webpages and provides a list of best-use cases. It distinguishes from siblings via usage examples and mentions auto and LLM modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Best for' section and examples provide clear context for when to use this tool. However, it does not explicitly state when not to use it or alternatives like maps_web or return_links.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

maps_webA

Browse and scrape any webpage with advanced proxy and rendering capabilities.

Best for:

  • Reading webpage content

  • Taking screenshots of websites

  • Verifying how a site looks from different countries

  • Bypassing anti-bot protections

  • Accessing JavaScript-rendered content

Key Features:

  • Geo-targeting: Access websites from different countries

  • JavaScript Rendering: Render SPAs and dynamic content

  • Residential/Mobile Proxies: Better success on challenging sites

  • Screenshots: Capture visual snapshots of pages

  • Anti-Bot Bypass: Multiple bypass levels for protected sites

  • Wait Controls: Wait for elements or time before capture

Usage Examples:

  1. Simple page browse:

{
  "name": "maps_web",
  "arguments": {
    "url": "https://example.com"
  }
}
  1. Screenshot for website:

{
  "name": "maps_web",
  "arguments": {
    "url": "https://example.de",
    "render_js": true,
    "json_response": true,
    "screenshot": true
  }
}
  1. Access Cloudflare-protected site:

{
  "name": "maps_web",
  "arguments": {
    "url": "https://protected-site.com",
    "bypass_level": "cloudflare_level_2",
    "residential": true,
    "render_js": true
  }
}
  1. Wait for dynamic content:

{
  "name": "maps_web",
  "arguments": {
    "url": "https://spa-app.com",
    "render_js": true,
    "wait_for": ".product-list",
    "wait": 2000
  }
}

Returns: HTML content, or JSON with screenshot (base64) if screenshot=true.

IMPORTANT - Default Behavior:

  • Always start with BASIC settings (just the URL)

  • Do NOT use advanced parameters (render_js, residential, bypass_level, premium) unless:

    1. The user explicitly requests them, OR

    2. A previous request failed AND the user gives permission to use them

If a request fails:

  • The error response will ask for permission to retry with advanced options

  • Wait for user confirmation before using advanced parameters

  • Never auto-enable advanced parameters without user consent

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
waitNo
mobileNo
scrollNo
countryNo
premiumNo
wait_forNo
render_jsNo
screenshotNo
device_typeNo
residentialNo
bypass_levelNo
keep_headersNo
session_numberNo
follow_redirectsNo
max_request_costNo
optimize_requestNo
return_status_codesNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but description comprehensively explains capabilities (geo-targeting, anti-bot, screenshots, wait controls) and return format. Lacks mention of potential side effects like cookies or rate limits, but overall transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections, bullet points, and code examples. Front-loads purpose and key features. Slightly long but every section adds value; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 18 parameters and no output schema, description provides thorough context: best-for, features, examples, default behavior, error handling, and return format. Missing explanations for a few parameters, but overall complete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, baseline is 4. Description explains many parameters via key features and usage examples (e.g., wait, wait_for, screenshot, render_js, bypass_level, residential). Some parameters (keep_headers, session_number) not mentioned, but coverage is high enough to justify a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for browsing and scraping webpages with advanced proxy and rendering capabilities. It distinguishes from sibling tools by listing specific features like geo-targeting and JavaScript rendering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Best for' scenarios and 'IMPORTANT - Default Behavior' instructions on when to use advanced parameters, requiring user confirmation for retries. This gives clear guidance on appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.0.1
    • First observedextract_data
    • First observedmaps_web
    • First observedreturn_links

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: maps_web for general browsing and scraping, extract_data for structured data extraction, and return_links for URL extraction. There is no functional overlap.

Naming Consistency4/5

All tools follow a verb_noun pattern with underscores (maps_web, extract_data, return_links). However, 'maps_web' is a slightly ambiguous verb choice, deviating from the more descriptive verbs like 'extract' and 'return'.

Tool Count4/5

Three tools is low but sufficient for a focused scraping toolkit. They cover the core tasks: browsing, data extraction, and link analysis. Additional tools (e.g., dedicated screenshot) could be added, but the current count is reasonable.

Completeness4/5

The tool surface covers the primary scraping workflows: browsing with advanced features (maps_web), structured extraction (extract_data), and link discovery (return_links). Minor gaps exist, such as lack of form interaction or session management, but core needs are met.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to operate a real, anti-bot-aware browser through Zyte API for navigating pages, clicking, typing, scrolling, taking screenshots, searching, and extracting structured data, with automatic proxy rotation and ban avoidance.
    15
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ScrapeOps/scrapeops-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server