Give Cursor's agent live web access — search, scrape, screenshot, and a real cloud browser — by adding the Scrapeless MCP server. 21 tools, one config file.
Clone this repo and Cursor picks the server up from .cursor/mcp.json.
Cursor reasons well over your codebase and cannot see the live web. That gap costs you every time you need to:
- Build a scraper against a real target — inspect the actual markup, write selectors, verify them, all in one session instead of guessing and re-running.
- Check a live API or docs page before writing the integration, rather than trusting stale training data.
- Pull competitor or market data into a file you then analyze in the editor.
- Screenshot a deployed page and have the agent describe what rendered.
- Cursor with MCP support
- Node.js 18+ (for
npx) - A Scrapeless API key — create a free account
Project scope (this repo — the server is available only in this workspace):
git clone https://github.com/<owner>/scrapeless-cursor.git
cd scrapeless-cursor
cp .env.example .env
export SCRAPELESS_API_KEY=your_key_here # export before launching Cursor
cursor .Global scope (every project): copy the same block into ~/.cursor/mcp.json.
Then open Settings → MCP and confirm scrapeless is listed with a green status and 21 tools. Use the agent in Agent mode — MCP tools are not offered in plain chat/edit modes.
The server reads SCRAPELESS_KEY, not SCRAPELESS_API_KEY. Verified behavior:
| Environment | Result |
|---|---|
SCRAPELESS_KEY set |
Works — tools respond |
Only SCRAPELESS_API_KEY set |
Server starts, then never responds — no error, just a hang |
| Neither set | Server starts, then never responds |
There is no "missing credentials" error; a tool call simply hangs, which in Cursor looks like the agent stalling. The config here maps one to the other ("SCRAPELESS_KEY": "${SCRAPELESS_API_KEY}"), so exporting SCRAPELESS_API_KEY is enough — but if you hand-write a config elsewhere, set SCRAPELESS_KEY.
Cursor must inherit the variable. ${SCRAPELESS_API_KEY} is expanded from Cursor's own environment, so export it before launching, or launch Cursor from a shell that has it. Launching from a desktop icon usually will not inherit your shell profile — if the value comes through empty, put the literal key in ~/.cursor/mcp.json instead (that file is outside your repo, so it is not committed).
verify_mcp.py speaks MCP over stdio — the same protocol Cursor uses — so you can confirm the server works independently of the editor:
export SCRAPELESS_API_KEY=your_key_here
python3 verify_mcp.py # list the tools
python3 verify_mcp.py --call # also scrape example.comReal output:
server: scrapeless-mcp-server 0.2.0
tools : 21
...
calling scrape_markdown on https://example.com ...
returned 184 characters of markdown
If this passes and Cursor still shows the server as failed, the problem is Cursor's environment, not the server.
Search and one-shot fetch — stateless, one call each: google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot.
Cloud browser session — stateful; browser_create first, browser_close last: browser_goto, browser_get_html, browser_get_text, browser_snapshot, browser_screenshot, browser_click, browser_type, browser_press_key, browser_scroll, browser_scroll_to, browser_wait, browser_wait_for, browser_go_back, browser_go_forward.
Full list with input schemas: results/tools.json.
Prefer scrape_markdown for reading a page — one call, least noise. Escalate to browser_* only when the task needs interaction or the page must settle first.
Name the tool. Cursor's agent picks correctly far more often when you do:
Use scrape_html on <url> and show me the markup around the product cards.
Then propose CSS selectors for title and price, write the scraper, and use
scrape_html again to confirm the selectors match.
Use scrape_markdown on <competitor pricing page> and save it to
snapshots/pricing-today.md. Diff it against the newest existing snapshot and
summarize only what changed.
Use browser_create, browser_goto <url>, browser_wait_for a selector that only
exists on the real content, then browser_get_html. If the HTML is under 20 KB
you are still holding the challenge page — wait longer and read again.
| Symptom | Cause and fix |
|---|---|
| Tool call hangs, agent stalls | SCRAPELESS_KEY missing in the server env. See the table above. |
| Server shows red / failed in Settings → MCP | Cursor did not inherit SCRAPELESS_API_KEY. Export before launch, or inline the key in ~/.cursor/mcp.json. |
| Agent never uses the tools | You are not in Agent mode, or the prompt did not name a tool. |
npx re-downloads every launch |
npm install -g scrapeless-mcp-server, then set "command": "scrapeless-mcp-server" with no args. |
| Browser tools error about no session | Call browser_create first. |
| A page comes back nearly empty | Read before the challenge cleared. browser_wait_for a content selector, then read. |
scrapeless-cursor/
├── .cursor/mcp.json # project MCP config — Cursor reads this
├── verify_mcp.py # stdio MCP self-check, no editor required
├── results/tools.json # live tool list with input schemas
└── LICENSE
- Product: Scraping Browser · Universal Scraping API
- Integration page: Scrapeless with Cursor
- Upstream server: scrapeless-ai/scrapeless-mcp-server
MIT — see LICENSE.