Cursor Plugin
The Browserless plugin for Cursor registers the hosted Browserless MCP server and signs you in with OAuth. Once it's installed, Cursor's agent can scrape, search, crawl, export pages, drive a stateful cloud browser, and run Lighthouse audits without leaving the editor.
Installation
Run this in Cursor chat:
/add-plugin browserless
Or open Settings → Plugins, search for Browserless, and click Install.
Authentication
Click Authenticate under Settings → Plugins → Browserless, sign in with your Browserless account, and approve access. Cursor handles the OAuth exchange and stores the credentials itself, so there's no token to paste or rotate by hand. Re-authenticate from the same panel at any time.
Manual configuration
On Cursor builds older than 3.13, or if you'd rather manage MCP config yourself, add the server to ~/.cursor/mcp.json with a token from your account dashboard:
{
"mcpServers": {
"browserless": {
"type": "http",
"url": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
}
}
}
}
Put the same JSON in <project-root>/.cursor/mcp.json to scope the server to one project. Project config wins over the global file when both exist. That file usually gets committed, so set the header to "Bearer ${env:BROWSERLESS_TOKEN}" there instead of the literal token. Cursor substitutes ${env:NAME} in url, headers, command, args, and env, so export BROWSERLESS_TOKEN before launching Cursor.
Restart Cursor, then check Settings → MCP. The browserless entry should list 14 tools. To use a region other than US West, see regional endpoints.
Tools
The plugin ships no tools of its own. It points Cursor at the hosted server, which exposes these:
| Tool | What it does |
|---|---|
browserless_agent | Stateful browser session. Snapshot, click, type, scroll, and evaluate across multi-step flows |
browserless_smartscraper | Fetch one URL as markdown, HTML, links, a screenshot, or a PDF |
browserless_crawl | Crawl a site from a seed URL and scrape every discovered page |
browserless_map | List all URLs on a site from its sitemap and links, ranked by relevance |
browserless_search | Web, news, and image search with optional per-result scraping |
browserless_export | Return a page's native content, or bundle it with its assets as a ZIP |
browserless_function | Run custom Puppeteer JavaScript in a cloud browser |
browserless_performance | Run a Lighthouse audit for performance, accessibility, best practices, SEO, and PWA |
browserless_skill | Load site-specific recipes on demand, such as cookie consent or CAPTCHA handling |
Five more tools (browserless_account, browserless_usage, browserless_logs, browserless_sessions, and browserless_profiles) read your account state and are documented in account tools. They're read-only and never return token or cookie values.
Reach for browserless_agent when the task needs state across steps, like logging in or clicking through a multi-page form. The stateless tools are faster and cheaper for one-shot work. See REST API tools and the browser agent for the full parameter lists.
Example: audit and fix page performance
Visual learner? Check out this video I Used AI to Fix My Website Performance (Cursor + Browserless) for a step-by-step tutorial.
browserless_performance runs Lighthouse against a live URL and returns the category scores inline. The full JSON report stays out of the conversation: over HTTP it comes back as an authenticated single-use download that expires after 15 minutes or when the MCP session ends. Ask Cursor to fetch that report when you want it acting on specific audits rather than the headline scores. In the video, that loop takes a PageSpeed score from 67 to 100.
Ask for the audit and the fix in one prompt:
Run browserless_performance on https://example.com, download the full
report, then fix the three largest performance opportunities in this
codebase and re-run the audit.
Point it at the whole site by mapping the URLs first:
Use browserless_map to list the URLs on https://example.com, then run
browserless_performance on the five most important pages and compare scores.
Lighthouse measures the deployed page, not your working tree, so deploy or expose a preview URL before you re-audit. For the same audit over HTTP, see the Performance API.
FAQ & Troubleshooting
The plugin doesn't appear under Settings → Plugins
Your Cursor build is older than 3.13. Update Cursor, or use the manual configuration above.
The browserless server connects but shows 0 tools
You're not authenticated. Click Authenticate under Settings → Plugins → Browserless. On a manual install, check the Authorization header reads Bearer followed by your token, with no quotes or trailing whitespace inside the value.
Tools are listed but every call returns 401 Unauthorized
The authorization was revoked or the token is wrong. Re-authenticate from Settings → Plugins → Browserless, or copy a fresh token from your account dashboard.
Calls fail with 429 Too Many Requests
Browserless returns 429 when the account is out of units and when concurrency limits are exceeded. Check your usage in the account dashboard first. If units remain, you're hitting the concurrency limit, so run fewer calls in parallel or retry with backoff.