Connect

Connect your assistant (MCP)

MCP (Model Context Protocol) is how an AI assistant such as Claude calls Scrapewise as a set of tools. The address is the same for everyone: https://mcp.scrapewise.ai/mcp.

How you sign in: every client sends your key in the Authorization: Bearer <key> header. There is no sign-in window and no OAuth. Paste a Read key if the assistant should only look. Paste a Full key if it should also create, run, change, delete or use the paid tools.

Make a key. Press your name at the bottom of the portal menu, then API Keys, type a Key name, pick the Read scope (the portal shows it as LLM_READ) to look, or the Full scope (LLM_FULL) to build and run, and press Generate API Key. Copy the key. See Read or Full.
In the same window API key generated, the tabs for Claude Code, Claude Desktop, Cursor and VS Code hold ready text with your key already in it.
Pick your client below and follow its steps.
Test it. Ask: “List my Scrapewise groups”. An empty list on a new account still proves the connection works.

Open Settings, Developer, then Edit Config. This opens the file claude_desktop_config.json. On a Mac it is ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json. You can also open the file there in any text editor.
Add the block below to mcpServers. Replace [YOUR KEY] with your key.
Quit Claude Desktop fully and open it again.

json

{
  "mcpServers": {
    "scrapewise": {
      "url": "https://mcp.scrapewise.ai/mcp",
      "headers": { "Authorization": "Bearer [YOUR KEY]" }
    }
  }
}

Run the command below in your terminal. Replace [YOUR KEY] with your key.
Check with claude mcp list. The server scrapewise should be there.

bash

claude mcp add scrapewise --transport http https://mcp.scrapewise.ai/mcp --header 'Authorization: Bearer [YOUR KEY]'

Add a custom connector with the address https://mcp.scrapewise.ai/mcp and an Authorization header with the value Bearer [YOUR KEY].
If your plan does not show a header field, use Claude Desktop or Claude Code instead.

Paste the block from the Cursor or VS Code tab of the window API key generated into the MCP file of the client.
Cursor uses the same block as Claude Desktop in ~/.cursor/mcp.json. VS Code names the list servers and needs "type": "http" on the entry.

Note

Never put the key in a web address. Use the header only. Revoke a key in API Keys if it was shared by mistake.

The gateway speaks MCP over HTTP (Streamable HTTP). Use it from code with an MCP client library. You can also send the raw messages.
Send POST https://mcp.scrapewise.ai/mcp with the headers Authorization: Bearer <key> (a Read key or a Full key, see Read or Full), Content-Type: application/json and Accept: application/json, text/event-stream. The first message is initialize.
Keep the Mcp-Session-Id header from the answer on every later call. A session ends after 15 minutes without use. Then send initialize again.
Send tools/list to see the tools. A Read key lists the read tools (48). A Full key lists all 114.
Send tools/call to run a tool. A Read key may call only the Read tools. A Full key may call every tool.
A wrong or revoked key gets 401 with WWW-Authenticate: Bearer realm="Scrapewise MCP".
The outcome tools are also plain REST calls on the portal API, for code that does not speak MCP. Base address https://portal.scrapewise.ai/api/scraper-api, header Authorization: Bearer <key>. Use a Full key for the paid routes and a Read key for the free ones, as the table shows.

The outcome routes, with the MCP tool each one is the same as:

Call	Key	MCP tool	What it does
`POST /api/scraper/outcome/local-businesses`	Full	`find_local_businesses`	Businesses on Google Maps for a search in a place. One page of up to 20 places
`POST /api/scraper/outcome/google-search`	Full	`google_search`	Google web, news or shopping results for 1 to 100 queries
`POST /api/scraper/outcome/amazon-search`	Full	`search_amazon`	Amazon products for a search phrase, on the Amazon site you pick
`POST /api/scraper/outcome/amazon-product`	Full	`get_amazon_product`	Amazon product pages by ASIN or address
`POST /api/scraper/outcome/amazon-seller-leads`	Full	`amazon_seller_leads`	The sellers behind an Amazon search with their published business contact details
`POST /api/scraper/outcome/google-trends`	Full	`google_trends`	Interest over time for one phrase
`POST /api/scraper/outcome/idealo-offers`	Full	`idealo_offers`	Every shop’s price for a product on idealo
`POST /api/scraper/outcome/page`	Full	`fetch_page`	One public web page as text or HTML
`POST /api/scraper/outcome/product-data`	Full	`get_product_data`	Name, price, availability, brand and codes from product pages of a shop
`POST /api/scraper/outcome/clean`	Read	`clean_product_data`	Free cleaning of rows you send: price in EUR, price per unit, remove duplicates. Nothing is fetched or stored
`GET /api/scraper/outcome/jobs/{jobId}`	Read	`get_results`	State, cost and rows of a long job. Free
`POST /api/scraper/outcome/jobs/{jobId}/cancel`	Full	`cancel_job`	Stops a long job. Rows it already collected stay and stay charged

Send "quote_only": true to get the exact price and your balance without spending anything. Send an idempotency_key and repeat it on a retry, so the request is answered and charged once. A small request answers at once with status: "DONE", rows, rowCount, costMicros, walletBalanceMicros and freeRequestsLeft. A big one answers status: "RUNNING" with a job_id: read it with GET /api/scraper/outcome/jobs/{jobId} and follow nextPage until the rows end. A Read key on a paid route gets 403. A wallet with no balance gets 402. Too many calls at the same moment get 429 with Retry-After.

bash

curl -X POST "https://mcp.scrapewise.ai/mcp" \
  -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: [SESSION ID FROM INITIALIZE]" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

python

import os, requests

r = requests.post(
    "https://mcp.scrapewise.ai/mcp",
    headers={
        "Authorization": f"Bearer {os.environ['SCRAPEWISE_KEY']}",
        "Accept": "application/json, text/event-stream",
        "Mcp-Session-Id": "[SESSION ID FROM INITIALIZE]",
    },
    json={"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
)
print(r.text)

javascript

const r = await fetch("https://mcp.scrapewise.ai/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCRAPEWISE_KEY}`,
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
    "Mcp-Session-Id": "[SESSION ID FROM INITIALIZE]",
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
});
console.log(await r.text());

Limits: about 60 requests a minute per key (429 with Retry-After), and an hourly cost counter on the gateway (429 cost_exceeded, wait for the next hour). Tools only: resources/list returns an empty list.

Connect with a Read key to look around. Ask for scrapewise_get_scraper_group_list (Read) to list your groups.
Read the rows of a group with scrapewise_get_scraper_data_group_client (Read).
To search the web or fetch pages, use a Full key and the outcome tools below. Ask the assistant to tell you the price first.
A big request answers with a job id. Fetch the result with get_results (Read). Stop it with cancel_job (Full).
Building scrapers needs a Full key. See Read a website.
If a tool answers HTTP 402, the wallet is out of balance. The assistant should stop and tell you. Paid tools need a Full key. See Wallet and billing.

The outcome tools:

find_local_businesses, google_search, search_amazon, google_trendsFull

fetch_page, get_product_dataFull

get_amazon_product, amazon_seller_leads, idealo_offersFull

cancel_jobFull

clean_product_data (free), get_resultsRead

Every other tool belongs to a feature page: scrapers, groups, rules, exports, matching and so on. The full list with Read or Full is on MCP tools.

Text a tool brings back from a web page is marked type: "scraped". It is untrusted. Your assistant must not follow instructions inside it. See MCP safety.

Many URLs: one automation, one list

To scrape many addresses, give one automation the whole list. Never make one automation per address. The tool is scrapewise_run_scraper_url_list (Full). Retry with the exact same name, so a repeat is not charged twice. The full steps are on Read a website.

Upload a file

If you have one file (CSV, JSON Lines or Excel), the tools scrapewise_create_file_scraper and scrapewise_update_file_scraper_file (both Full) turn it into an upload scraper. Small files go in the call. For a bigger file the tool returns one ready upload command. See Upload a file.

Out of balance, 402 through MCP

When the wallet has no balance and no free requests, a billable tool returns a result with isError: true. The text is HTTP 402 followed by the body with the code WALLET_INSUFFICIENT_BALANCE. The assistant should stop and tell you, not retry. A match run that cannot start answers FLOW_RUN_SERVER_WALLET_LOW instead. Both are explained on Wallet and billing.

Errors you may see

401 Unauthorized

The key is missing, wrong or revoked. Check Bearer and a space before the key.

403 scope_rejected

The tool needs a Full key and you have a Read key. Make a Full key.

Only a few tools are listed

You are on a Read key. Make a Full key to list the tools that create and run.

HTTP 402 WALLET_INSUFFICIENT_BALANCE

No balance and no free requests. Top up in the portal and repeat the call. Do not retry before that.

429 Too Many Requests

Wait the seconds in Retry-After.

429 cost_exceeded

The hourly cost counter is full. Wait for the next hour.

503 Service Unavailable

The gateway is busy for a moment. Wait and retry.

Questions

Is there an OAuth sign-in?

No. Every client uses a key in the Authorization header.

Which key do I paste?

A Read key to look at your data. A Full key to build, run, delete and use the paid tools. See Read or Full.

Does it cost anything to connect?

No. Listing and reading are free. Tools that fetch pages are charged per page delivered, see Wallet and billing.

Why does the tool list show tools but no resources?

Scrapewise offers tools only. The resources list is empty.

Can I use it from n8n?

Yes. See n8n.

Last updated 4 November 2026