Sandbox::https://help.decodo.com/docs/mcp

More information can be found in GitHub repository.

Connect LLMs and AI agents to live web data using MCP (Model Context Protocol). The Decodo MCP Server lets you scrape websites, search engines, eCommerce platforms, and social media directly from AI tools like Claude, Cursor, and Windsurf, all without the need to build scraping infrastructure from scratch.

Structured outputs in JSON, Markdown, and screenshots
Server-side JavaScript rendering and anti-bot handling
125M+ IPs across 195+ locations

What is Decodo MCP server?

The Decodo MCP Server is a web scraping layer for AI agents. It connects MCP-compatible clients to Decodo’s Web Data API, enabling:

Web scraping for LLMs
Real-time data retrieval for RAG
AI agent browsing and research
Structured data extraction from dynamic websites

Instead of maintaining proxies, parsers, and retry logic, you get a single integration point for reliable web data access.

Why use MCP for web scraping?

Model Context Protocol (MCP) is the emerging standard for connecting AI agents to external tools and data sources. With MCP:

Agents can call tools dynamically
Integrations stay standardized
Workflows scale across environments

The Decodo MCP Server gives your agents reliable, production-ready web access through this standard.

Key features

Web scraping for AI agents, no infrastructure required. Scrape any website, including JavaScript-heavy pages, without handling proxy rotation, CAPTCHA solving, or anti-bot systems. Structured outputs for LLM workflows. Markdown (LLM-ready), JSON (for structured pipelines), and screenshots (for visual context), built for RAG pipelines, AI research agents, and automation flows. Built-in support for popular targets. Ready-made tools for Google (SERPs), Amazon, Walmart, and Target (eCommerce), TikTok and YouTube (social media), and Google AI Mode. Running the server yourself adds Bing, Google Ads, Google Lens, ChatGPT, and Perplexity (see Tools). Global proxy infrastructure. 115M+ residential IPs, 195+ geo-locations, and a 99.99% success rate on even the most protected targets. Modular MCP toolsets. Enable only what you need: web, search, ecommerce, social_media, ai for cleaner tool selection and better agent performance. Fast time to value. From API key to first scrape in minutes, no setup overhead.

Use cases

Use the Decodo MCP Server when you need web scraping for AI agents, structured data extraction at scale, reliable access to dynamic websites, real-time data for RAG, or an alternative to building scraping infrastructure from scratch. Common scenarios:

AI-powered web scraping – give LLMs the ability to collect fresh data instead of relying on static training data.
RAG with live data – pull real-time Google, Bing, and AI search results into retrieval pipelines.
eCommerce intelligence – track product prices, listings, and sellers across marketplaces without getting blocked.
Social media data collection – gather posts, channels, and engagement data from TikTok and YouTube.
Travel and price aggregation – build tools that collect live pricing and availability across websites.

Quick start

Create a free account at dashboard.decodo.com – up to 10K free requests, no credit card required.
Get an MCP client like Claude, Cursor, Windsurf, or any other MCP-compatible tool.
Connect. If your client supports OAuth, add the server URL and sign in – no API key and nothing to install (see Sign in with OAuth). Otherwise, copy your Web Data API key from your Web Data API subscription on the dashboard and pass it as a header (see Authentication). Older plans have a basic authentication token, which also works.
Configure the MCP server in your AI client (see configuration examples below).

You only need Node.js 22+ if you run the server locally with npx. The hosted server at https://mcp.decodo.com/mcp requires no installation.

Connecting to Decodo’s MCP server

Open your preferred MCP client and add the following configuration (see examples for Claude Code, Cursor, Windsurf below):

{
  "mcpServers": {
    "Decodo": {
      "url": "https://mcp.decodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Authentication

Credential	Where to get it	Hosted server header	Local server env
API key (recommended)	Web Data API subscription on the dashboard	`Authorization: Bearer <api_key>`	`SCRAPER_API_TOKEN=<api_key>`
Basic authentication token (older plans)	Web Scraping API page on the dashboard	`Authorization: Basic <basic_auth_token>`	`SCRAPER_API_TOKEN=<basic_auth_token>`

The local server reads either credential from SCRAPER_API_TOKEN and works out which one it got. The hosted server supports OAuth 2.1, so clients that implement it can connect without an API key. Add the server URL with no headers block at all:

{
  "mcpServers": {
    "Decodo": {
      "url": "https://mcp.decodo.com/mcp"
    }
  }
}

Your client opens the Decodo dashboard, you approve the connection, and the client stores the token itself. There is no API key to copy and nothing to install.

OAuth support varies by client. If yours doesn’t offer a sign-in prompt, use the Authorization header shown above instead.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config.
Add to claude_desktop_config.json:

{
  "mcpServers": {
    "Decodo": {
      "command": "npx",
      "args": ["-y", "@decodo/mcp-server"],
      "env": {
        "SCRAPER_API_TOKEN": "<api_key>",
        "TOOLSETS": "web,ai"
      }
    }
  }
}

Save and restart Claude Desktop.

Cursor

Open Settings → MCP.
Click Add a new global MCP server (opens mcp.json).
Add the same configuration as above.
Save — look for a green status indicator next to Decodo.

Windsurf

Open Settings → Windsurf Settings.
Scroll to Cascade → Add custom server + (opens mcp_config.json).
Add the same configuration as above.
Save and restart Windsurf.

Test your setup

Once connected, try this prompt in your client: ▎ “Scrape the titles of the top 5 articles from Hacker News” You should get a structured list back within seconds. If you see an auth error, double-check your API key on the dashboard.

Local development

Only needed if you want to change the server code.

Build and run the server from this repository

Prerequisites

Node.js 22.0+
An MCP client - popular choices are Claude Desktop and Cursor

Step-by-step guide

Clone the mcp-server repository:

git clone https://github.com/Decodo/mcp-server

Run the following commands in the terminal:

cd mcp-server
npm install
npm run build

Take note of your build location:

cd build/
pwd

Adding index.js to the end of this directory, your build file location should look something like this:

/Users/your.user/projects/mcp-server/build/index.js

Update your MCP client with the server information:

{
  "mcpServers": {
    "decodo-mcp": {
      "command": "node",
      "args": ["/Users/your.user/projects/mcp-server/build/index.js"],
      "env": {
        "SCRAPER_API_TOKEN": "<api_key>"
      }
    }
  }
}

Toolsets

Tools are organized into toolsets. Which ones you get depends on how you connect.

Claude (official connector)

The Decodo connector in Claude’s connector directory is served from a dedicated endpoint, https://mcp.decodo.com/claude, and includes the Web Data API tools only. This set is fixed – the toolsets query parameter is ignored on this endpoint:

Toolset	Tools
`web`	`scrape_as_markdown`, `screenshot`, `map`, `crawl_start`, `crawl_status`, `crawl_results`, `crawl_cancel`
`search`	`search`

Any MCP client

You can selectively enable specific toolsets by passing a comma-separated list via the toolsets query parameter:

    "Decodo MCP Server": {
      "url": "https://mcp.decodo.com/mcp?toolsets=web,ai",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }

When no toolsets are specified, every toolset is enabled.

Nine tools are hidden on the hosted server by default and are available only when you run the server yourself: bing_search, google_ads, google_lens, chatgpt, perplexity, target_product, tiktok_shop_url, tiktok_post, and youtube_search.They are listed in the toolsets below because the toolsets describe the full server. In practice https://mcp.decodo.com/mcp exposes 24 of the 33 tools, so requesting ?toolsets=ai on the hosted server returns google_ai_mode only. If you run the server yourself, set HIDDEN_TOOLS= (empty) to enable all of them.

Toolset	Tools
`web`	`scrape_as_markdown`, `screenshot`, `map`, `crawl_start`, `crawl_status`, `crawl_results`, `crawl_cancel`
`search`	`search`, `google_search`, `google_ads`, `google_lens`, `google_travel_hotels`, `bing_search`
`ecommerce`	`amazon_search`, `amazon_product`, `amazon_pricing`, `amazon_sellers`, `amazon_bestsellers`, `walmart_search`, `walmart_product`, `target_search`, `target_product`, `tiktok_shop_search`, `tiktok_shop_product`, `tiktok_shop_url`
`social_media`	`tiktok_post`, `youtube_metadata`, `youtube_channel`, `youtube_subtitles`, `youtube_search`
`ai`	`chatgpt`, `perplexity`, `google_ai_mode`

Tools

The server exposes the following tools. Tools marked Local only are hidden on the hosted server and work when you run the server yourself (see Toolsets).

Tools marked API key only reach the Web Data API, which basic authentication tokens cannot call. Using one returns: “This tool needs a Decodo API key; Basic authentication tokens cannot use the Web Data API.”

Tool	Description	Example prompt
`scrape_as_markdown`	Scrapes any target URL, expects a URL to be given via prompt. Returns results in Markdown.	Scrape peacock.com from a US IP address and tell me the pricing.
`screenshot`	Captures a screenshot of any webpage and returns it as a PNG image.	Take a screenshot of github.com from a US IP address.
`map`	Lists the URLs on a website without fetching their content. API key only.	Map docs.decodo.com and list the pages under /scraping-api.
`crawl_start`	Starts crawling a website and returns the crawl id without waiting. API key only.	Crawl the first 10 pages of decodo.com/blog.
`crawl_status`	Reports a crawl’s progress: pages discovered, completed and failed. API key only.	Is my crawl finished yet?
`crawl_results`	Returns crawled pages as Markdown, a few at a time with a cursor. API key only.	Show me the pages my crawl found.
`crawl_cancel`	Stops a running crawl; pages crawled so far stay readable. API key only.	Cancel my crawl.
`search`	Searches the web and returns ranked results. API key only.	Search the web for MCP server hosting options.
`google_search`	Scrapes Google Search for a given query, and returns parsed results.	Scrape Google Search for shoes and tell me the top position.
`google_ads`	Scrapes Google Ads search results. Local only.	Scrape Google Ads for laptop and show me the top ads.
`google_lens`	Scrapes Google Lens image search results. Local only.	Search Google Lens for this image: `https://example.com/image.jpg`
`google_ai_mode`	Scrapes Google AI Mode (Search with AI) results.	Ask Google AI Mode: What are the top three dog breeds?
`google_travel_hotels`	Scrapes Google Travel Hotels search results.	Search Google Travel Hotels for hotels in Paris.
`amazon_search`	Scrapes Amazon Search for a given query, and returns parsed results.	Scrape Amazon Search for wireless keyboard.
`amazon_product`	Scrapes Amazon Product page.	Scrape Amazon product B09H74FXNW and show me the details.
`amazon_pricing`	Scrapes Amazon Product pricing information.	Get pricing for Amazon product B09H74FXNW.
`amazon_sellers`	Scrapes Amazon Seller information.	Get information about Amazon seller A1R0Z7FJGTKESH.
`amazon_bestsellers`	Scrapes Amazon Bestsellers list.	Show me Amazon bestsellers in electronics.
`walmart_search`	Scrapes Walmart Search for a given query, and returns parsed results.	Scrape Walmart Search for camping tent.
`walmart_product`	Scrapes Walmart Product page.	Scrape Walmart product 15296401808.
`target_search`	Scrapes Target Search for a given query, and returns parsed results.	Scrape Target Search for kitchen appliances.
`target_product`	Scrapes Target Product page. Local only.	Scrape Target product 92186007.
`tiktok_post`	Scrapes a TikTok post URL for structured data (e.g. engagement, caption, hashtags). Local only.	Scrape this TikTok post: https://www.tiktok.com/@nba/video/7393013274725403950
`tiktok_shop_search`	Scrapes TikTok Shop Search for a given query, and returns parsed results.	Scrape TikTok Shop Search for phone cases.
`tiktok_shop_product`	Scrapes TikTok Shop Product page.	Scrape TikTok Shop product 1731541214379741272.
`tiktok_shop_url`	Scrapes TikTok Shop page by URL. Local only.	Scrape this TikTok Shop URL: https://www.tiktok.com/shop/s?q=HEADPHONES
`youtube_metadata`	Scrapes YouTube video metadata.	Get metadata for YouTube video dFu9aKJoqGg.
`youtube_channel`	Scrapes YouTube channel videos.	Scrape YouTube channel @decodo_official.
`youtube_subtitles`	Scrapes YouTube video subtitles.	Get subtitles for YouTube video L8zSWbQN-v8.
`youtube_search`	Search YouTube videos. Local only.	Search YouTube for “How to care for chinchillas”.
`bing_search`	Scrapes Bing Search results. Local only.	Search Bing for laptop reviews.
`chatgpt`	Sends a single prompt to ChatGPT and returns its answer (no conversation history). Local only.	Ask ChatGPT to explain quantum computing in simple terms.
`perplexity`	Sends a single prompt to Perplexity and returns its answer (no conversation history). Local only.	Ask Perplexity what the latest trends in web development are.

Parameters

The following parameters are inferred from user prompts:

Parameter	Description
`jsRender`	Renders target URL in a headless browser.
`geo`	Sets the country from which the request will originate.
`locale`	Sets the locale of the request.
`tokenLimit`	Maximum number of characters to return (default 45000). Useful if the context window is small.
`prompt`	Prompt to send to AI tools (`chatgpt`, `perplexity`).
`search`	Activates ChatGPT’s web search functionality (`chatgpt` only).
`xhr`	When true, includes XHR or fetch responses in the scrape result where supported (e.g. `tiktok_post`).
`deviceType`	Device type to emulate (`desktop`, `mobile`, `tablet`). Parsed targets are stricter: Amazon tools are desktop-only so they omit it, and `bing_search`/`google_ai_mode` accept `desktop` and `mobile` only.
`domain`	Domain to use for the request (e.g., `amazon.com`, `amazon.co.uk`, `bing.com`).
`pageFrom`	Starting page number for pagination.
`deliveryZip`	ZIP code for delivery location (Target, Walmart).
`storeId`	Store ID for local inventory (Walmart).
`country`	Country for TikTok Shop requests.
`limit`	Maximum number of results to return (e.g., YouTube channel videos).
`language_code`	Language code for subtitles (e.g., `en`, `es`).

Web Data API parameters

These apply to search, map, and the crawl_* tools.

Parameter	Description
`limit`	Maximum number of results. Defaults to 10. Max 100 for `search` and `crawl_start`, 500 for `map`.
`maxDepth`	How many links deep to crawl, 1–10000 (`crawl_start`).
`sitemap`	How to use the site’s sitemap: `include`, `only`, or `skip`.
`domainFilter`	Which hosts to follow: `domain`, `subdomain`, or `all`.
`selectPaths`	Only visit URLs matching these patterns. Repeatable.
`excludePaths`	Skip URLs matching these patterns. Repeatable.
`page`	Result page number (`search`).
`cursor`	Pagination cursor for fetching the next batch (`crawl_results`).

limit defaults to 10, so an unqualified “crawl this site” returns 10 pages. Say how many you want – for example, “Crawl the first 200 pages of decodo.com/blog”.

Examples

Scraping geo-restricted content

Query your AI agent with the following prompt:

Scrape peacock.com from a German IP address and tell me the pricing.

This prompt will say that peacock.com is geo-restricted. To bypass the geo-restriction:

Scrape peacock.com from a US IP address and tell me the pricing.

Limiting number of response tokens

Long pages are truncated to tokenLimit characters (45000 by default) to avoid overflowing the context window. When content is cut, the result says so – “Truncated to N of M characters. Call again with a higher tokenLimit to get more.” – and when nothing was cut it confirms “Full website content retrieved.” You can raise the limit from your prompt:

Scrape hacker news, return 50k tokens.

If your agent has a big context window, tell it to return full content:

Scrape hacker news, return full content.

Support

Need help or just want to say hello? Our support is available 24/7.
You can also reach us anytime via email at support@decodo.com.

Feedback

Can’t find what you’re looking for? Request an article!
Have feedback? Share your thoughts on how we can improve.

ABOUT

RESIDENTIAL PROXIES

STATIC RESIDENTIAL (ISP) PROXIES

DATACENTER PROXIES

FREE PROXIES

SITE UNBLOCKER

WEB DATA API

VIDEO DOWNLOADER

DECODO TOOLS

AI

INTEGRATIONS

ACCOUNT & DASHBOARD

PAYMENTS

TROUBLESHOOTING

TIPS & TRICKS

USEFUL LINKS

MCP Server

What is Decodo MCP server?

Why use MCP for web scraping?

Key features

Use cases

Quick start

Connecting to Decodo’s MCP server

Authentication

Claude Desktop

Cursor

Windsurf

Test your setup

Local development

Toolsets

Claude (official connector)

Any MCP client

Tools

Parameters

Web Data API parameters

Examples

Scraping geo-restricted content

Limiting number of response tokens

Support

Feedback

​What is Decodo MCP server?

​Why use MCP for web scraping?

​Key features

​Use cases

​Quick start

​Connecting to Decodo’s MCP server

​Authentication

​Sign in with OAuth

​Claude Desktop

​Cursor

​Windsurf

​Test your setup

​Local development

​Toolsets

​Claude (official connector)

​Any MCP client

​Tools

​Parameters

​Web Data API parameters

​Examples

​Scraping geo-restricted content

​Limiting number of response tokens

Support

Feedback

What is Decodo MCP server?

Why use MCP for web scraping?

Key features

Use cases

Quick start

Connecting to Decodo’s MCP server

Authentication

Sign in with OAuth

Claude Desktop

Cursor

Windsurf

Test your setup

Local development

Toolsets

Claude (official connector)

Any MCP client

Tools

Parameters

Web Data API parameters

Examples

Scraping geo-restricted content

Limiting number of response tokens