Scrapeless Cursor

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.

Use case

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.

Requirements

• Cursor with MCP support
• Node.js 18+ (for npx)
• A Scrapeless API key — create a free account

Setup

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 one thing that will bite you

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 before you trust it

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.com

Real 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.

The 21 tools

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.

Prompts that work

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.

Troubleshooting

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.

Project structure

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

Related

• Product: Scraping Browser · Universal Scraping API
• Integration page: Scrapeless with Cursor
• Upstream server: scrapeless-ai/scrapeless-mcp-server

License

MIT — see LICENSE.