ScrapeOps MCP Server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ScrapeOps MCP ServerScrape https://example.com and extract the title"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/mcpManual Installation
npm install -g @scrapeops/mcpConfiguration
Environment Variables
Variable | Required | Description |
| Yes | Your ScrapeOps API key from scrapeops.io |
How It Works
The MCP server uses a simple, single-request approach:
Basic Request: If no options are specified, a basic request is made (URL only)
User-Specified Options: If options like
render_js,residential, orpremiumare specified, they are used directlyOn Failure: Returns helpful error with suggestions - the AI/user decides what to do next
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
Open Cursor Settings
Go to Features > MCP Servers
Click "+ Add new global MCP server"
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-mcpThe 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-keyheader in the configuration (as shown above), orVia the
SCRAPEOPS_API_KEYenvironment 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_webwithbypass_level='generic_level_3'andresidential=trueto 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_ATTEMPTSenvironment variable
Custom Configuration Example:
# Enable retries with 3 attempts
export SCRAPEOPS_RETRY_MAX_ATTEMPTS=3
export SCRAPEOPS_RETRY_INITIAL_DELAY=1000Error Handling
Status Code | Error | Resolution |
401 | Invalid API Key | Check your |
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 testAPI 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
π Documentation
π Report Issues
Available Tools
3 toolsextract_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:
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
}
}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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| mode | Yes | ||
| wait | No | ||
| mobile | No | ||
| country | No | ||
| premium | No | ||
| wait_for | No | ||
| render_js | No | ||
| data_schema | No | ||
| device_type | No | ||
| residential | No | ||
| bypass_level | No | ||
| keep_headers | No | ||
| session_number | No | ||
| response_format | Yes | json | |
| follow_redirects | No | ||
| max_request_cost | No | ||
| optimize_request | No |
TDQS
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.
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.
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.
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.
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.
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:
Simple page browse:
{
"name": "maps_web",
"arguments": {
"url": "https://example.com"
}
}Screenshot for website:
{
"name": "maps_web",
"arguments": {
"url": "https://example.de",
"render_js": true,
"json_response": true,
"screenshot": true
}
}Access Cloudflare-protected site:
{
"name": "maps_web",
"arguments": {
"url": "https://protected-site.com",
"bypass_level": "cloudflare_level_2",
"residential": true,
"render_js": true
}
}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:
The user explicitly requests them, OR
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
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| wait | No | ||
| mobile | No | ||
| scroll | No | ||
| country | No | ||
| premium | No | ||
| wait_for | No | ||
| render_js | No | ||
| screenshot | No | ||
| device_type | No | ||
| residential | No | ||
| bypass_level | No | ||
| keep_headers | No | ||
| session_number | No | ||
| follow_redirects | No | ||
| max_request_cost | No | ||
| optimize_request | No | ||
| return_status_codes | No |
TDQS
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.
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.
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.
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.
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.
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.
return_linksA
Extract and categorize all URLs from a webpage.
Best for:
Discovering all links on a page
Building sitemaps
Finding all assets (images, scripts, stylesheets)
Web crawling and link analysis
Identifying internal vs external links
What it extracts:
Links from , tags
Images from ,
Scripts from
Stylesheets from
Media from , ,
Embedded content from , ,
URLs from CSS url() functions
Meta refresh redirects
Open Graph and meta image URLs
URL Processing:
Converts relative URLs to absolute
Removes duplicates
Filters out mailto:, tel:, javascript:, data: URLs
Categorizes into pages vs assets
Returns: JSON with two arrays:
pages: HTML documents and navigational URLs
assets: Static resources (js, css, images, fonts, media)
Usage Examples:
Basic URL extraction:
{
"name": "return_links",
"arguments": {
"url": "https://example.com"
}
}Extract URLs from protected site:
{
"name": "return_links",
"arguments": {
"url": "https://protected-site.com",
"bypass_level": "generic_level_1"
}
}Geo-targeted extraction:
{
"name": "return_links",
"arguments": {
"url": "https://example.de",
"country": "de"
}
}| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| mobile | No | ||
| country | No | ||
| premium | No | ||
| residential | No | ||
| bypass_level | No | ||
| session_number | No | ||
| max_request_cost | No | ||
| optimize_request | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It details URL processing (relative to absolute, dedup, filtering), categorization into pages vs assets, and the JSON output structure. Example usage clarifies parameter behavior for bypass_level and country.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections (Best for, What it extracts, URL Processing, Returns, Usage Examples). It is longer than necessary but front-loads key information and uses clear formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no output schema, and no annotations, the description covers functionality, output structure, and processing well. However, it lacks error handling, rate limit info, and full parameter descriptions, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema). The description only provides examples for url, bypass_level, and country, leaving 6 undocumented parameters (mobile, premium, residential, etc.) unexplained. This fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it extracts and categorizes URLs from a webpage. It lists specific elements (links, images, scripts, etc.) and processing steps. Sibling tools (maps_web, extract_data) are distinct in purpose, so no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a 'Best for' section listing use cases like discovering links, building sitemaps, web crawling. It gives clear context for when to use, but does not explicitly state when not to use or compare to siblings. Lacks exclusion criteria.
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.
3 tool updates
v1.0.1- First observed
extract_data - First observed
maps_web - First observed
return_links
TDQS
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.
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'.
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.
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
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
Enable language models to perform advanced AI-powered web scraping with enterprise-grade reliabiliβ¦
Crawl, scrape, search the web, and automate browsers at scale with anti-bot bypass.
Web scraping for AI agents. Extract text and metadata from any URL worldwide. $0.005/page.
Reliable web access for AI agents: smart HTTP, rotating proxies, and full-browser rendering.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to scrape any website by providing tools for JavaScript rendering, antibot bypass, and automatic captcha solving. It supports synchronous, asynchronous, and batch scraping operations with built-in proxy rotation.5207MIT
- AlicenseAqualityFmaintenanceEnables AI agents to crawl, scrape, search, and automate browsers with anti-bot bypass, providing fast web access via 22 tools.22503MIT
- FlicenseBqualityBmaintenanceEnables AI agents to browse and extract data from any public website via Bright Data's cloud infrastructure, handling proxy rotation, CAPTCHA solving, and JavaScript rendering.57-
- FlicenseNot gradedqualityBmaintenanceEnables 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
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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