# ScrapingBee Remote MCP Server

> Connect MCP-capable AI clients to ScrapingBee tools for live scraping, search, extraction, ecommerce, and YouTube tasks.

## Endpoint and authentication

```text
https://mcp.scrapingbee.com/mcp?api_key=YOUR_API_KEY
```

- Remote MCP uses the `api_key` query parameter, not a Bearer header or OAuth flow.
- Keep the complete endpoint URL out of source control because it contains the API key.

## Cursor and Claude Desktop configuration

Bridge the remote Streamable HTTP server through `mcp-remote`:

```json
{
  "mcpServers": {
    "scrapingbee": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.scrapingbee.com/mcp?api_key=YOUR_API_KEY"
      ]
    }
  }
}
```

Cursor can use `~/.cursor/mcp.json` globally or `.cursor/mcp.json` per project. Include “use scrapingbee mcp” in a prompt when routing must be explicit.

For Claude Desktop, put the same `mcpServers` entry in its developer config, restart the application, and enable the connector. Any client with native Streamable HTTP support can connect directly to the endpoint; clients that need stdio can use the `mcp-remote` bridge. Node.js and `npx` must be installed for the bridge.

## ChatGPT setup

Custom MCP apps are supported on ChatGPT Plus/Pro (read/fetch tools) and Business/Enterprise/Edu (full MCP support is beta). On chatgpt.com:

1. Enable developer mode under Settings → Apps → Advanced Settings.
2. Create an app with Server URL `https://mcp.scrapingbee.com/mcp?api_key=YOUR_API_KEY`.
3. Select **No Auth** because the API key is embedded in the URL, acknowledge the warning, and connect.
4. Invoke it with `@ScrapingBee` in a prompt.

Workspace admins may need to enable custom apps before Business/Enterprise users can add one.

## Tools

| Group | Tools |
| --- | --- |
| HTML | `get_page_text`, `get_page_html`, `extract_page_data`, `get_screenshot`, `get_file` |
| Search / AI | `fast_search`, `get_google_search_results`, `ask_chatgpt`, `ask_gemini` |
| E-commerce | `get_amazon_search_results`, `get_amazon_product_details`, `get_amazon_pricing`, `get_walmart_search_results`, `get_walmart_product_details` |
| YouTube | `get_youtube_search_results`, `get_youtube_video_metadata`, `get_youtube_video_subtitles` |
| Account | `get_scrapingbee_usage` |

- Use `fast_search` before full Google search when a simple result list is enough.
- Use `get_google_search_results` for news, maps, shopping, images, Lens, or AI mode.
- The first four HTML tools support stealth proxy; `get_file` does not because it does not render JavaScript.
- All five HTML tools accept `premium_proxy`, `custom_google`, and `country_code`. Start without a proxy; retry with `premium_proxy: true` for a block, then `stealth_proxy: true` where supported.
- Ask the MCP client to inspect the live `tools/list` schema before forming a call. It is the authoritative source for each tool's parameter shapes.

## Coverage gaps

The remote tool set has no general CLI/crawl/batch/export tool and no write/mutation tool. Use the matching direct API or another documented integration for those capabilities.

`get_file` downloads files without browser rendering, so it cannot use stealth proxy. The HTML tools have differing return types (text/Markdown, HTML, extracted JSON, screenshot, or binary file); do not assume all accept identical rendering/extraction controls beyond the parameters exposed by `tools/list`.

## Limits and troubleshooting

- MCP calls consume ScrapingBee credits at the same rate as their underlying endpoints; the server adds no surcharge.
- The hosted server has shared global concurrency and can return `429` even when the account's own plan limit is acceptable. Use exponential backoff; the account concurrency limit still applies.
- Missing-key error: ensure the complete `?api_key=...` query string is present. Invalid/revoked/out-of-credit key: expect `401` and check the dashboard.
- If Cursor or Claude fails to finish the handshake, confirm Node.js and `npx` work, then run the `mcp-remote` command shown above. A healthy bridge reports a Streamable HTTP connection and proxy establishment. If that works, recheck the client configuration and reload the client.

```bash
npx mcp-remote "https://mcp.scrapingbee.com/mcp?api_key=YOUR_API_KEY"
```