mcp-server

# Decodo MCP Server

[![](https://dcbadge.limes.pink/api/server/https://discord.gg/Ja8dqKgvbZ)](https://discord.gg/Ja8dqKgvbZ)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=Decodo&config=eyJ1cmwiOiJodHRwczovL21jcC5kZWNvZG8uY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8YXBpX2tleT4ifX0%3D)

<p align="center">
<a href="https://dashboard.decodo.com/integrations?utm_source=github&utm_medium=social&utm_campaign=mcp_server"> <img src="https://github.com/user-attachments/assets/a1e52a9e-3da1-4081-b3c6-053aafb8f196"/></a>

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 Scraping 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 and Bing (SERPs), Amazon,
Walmart, and Target (eCommerce), Reddit, TikTok, and YouTube (social media), and ChatGPT and
Perplexity (AI search).

**Global proxy infrastructure.** 125M+ 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 Reddit,
  TikTok, and YouTube.
- **Travel and price aggregation** – build tools that collect live pricing and availability across
  websites.

## Quick start

1. **Create a free account** at [dashboard.decodo.com](https://dashboard.decodo.com/) – up to 2K
   free requests, no credit card required.
2. **Get your API key.** Copy your Web Data API key from your Web Data API subscription on the
   [dashboard](https://dashboard.decodo.com/web-data/playground). Older plans have a basic
   authentication token, which also works (see [Authentication](#authentication)).
3. **Download Node.js 18+** from https://nodejs.org.
4. **Get MCP client** like Claude Desktop, Cursor, Windsurf or other MCP-compatible tools.
5. **Configure the MCP server** in your AI client (see configuration examples below).

## Connecting to [Decodo's MCP server](https://mcp.decodo.com/mcp)

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

```
{
  "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](https://dashboard.decodo.com/web-data/playground) | `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.

### Claude Desktop

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

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

3. Save and restart Claude Desktop.

### Cursor

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

### Windsurf

1.  Open Settings → Windsurf Settings.
2.  Scroll to Cascade → Add custom server + (opens mcp_config.json).
3.  Add the same configuration as above.
4.  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.

## Optional: enable specific toolsets

# Running the MCP server locally

<details>

### Prerequisites

- Node.js 18.0+
- An MCP client - popular choices are [Claude Desktop](https://claude.ai/download) and
  [Cursor](https://www.cursor.com/)

### Step-by-step guide

1. Clone this repository:

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

2. Run the following commands in the terminal:

```
cd decodo-mcp-server
npm install
npm run build
```

3. 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/decodo-mcp/build/index.js
```

4. Update your MCP client with the server information:

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

</details>

## Toolsets

Tools are organized into toolsets. 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, all tools are registered.

| Toolset        | Tools                                                                                                                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web`          | `scrape_as_markdown`, `screenshot`                                                                                                                                                                                                  |
| `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` | `reddit_post`, `reddit_subreddit`, `reddit_user`, `tiktok_post`, `youtube_metadata`, `youtube_channel`, `youtube_subtitles`, `youtube_search`                                                                                       |
| `ai`           | `chatgpt`, `perplexity`, `google_ai_mode`                                                                                                                                                                                           |

## Tools

The server exposes the following tools:

| Tool                   | Descr