Browserless MCP in Cursor
Cursor connects to the hosted Browserless MCP server through the Browserless plugin from the Cursor Marketplace, or through a manual mcp.json entry with OAuth or an API token header. Once it's connected, Cursor can scrape, search, crawl, and drive a cloud browser with the Browserless MCP tools.
- A Browserless API token from your account dashboard, or a Browserless account for OAuth sign-in
- Cursor installed
Connect to the hosted server
The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.
Install the plugin (recommended). In Cursor 3.13 or later, open Cursor Settings → Plugins, search for Browserless, click Install, then Authenticate and sign in with your Browserless account. You can also run /add-plugin browserless in chat. The plugin uses OAuth, so there's no token to copy, and Cursor stores the credentials itself. It's also listed on the Cursor Marketplace.
Add the server in one click. If you'd rather not use the plugin, add the MCP server directly. Cursor opens an install prompt and then asks you to sign in to your Browserless account. You don't need this if you installed the plugin.
Add to CursorConfigure it manually. On older Cursor builds, or to manage the config yourself, add to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one project:
{
"mcpServers": {
"browserless": {
"url": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
}
}
}
}
To sign in with OAuth instead, drop the headers block. Cursor prompts you to sign in to your Browserless account.
To use a region other than US West, add an x-browserless-api-url header, or a browserlessUrl query parameter on the server URL for clients that only take a URL. See regional endpoints.
Run the server locally
To run the MCP server process on your machine instead, use the @browserless.io/mcp npm package over stdio. You need Node.js 24 or newer. Browser work still runs on Browserless, so this is mainly for pinning a server version (add it to the package name, for example @browserless.io/mcp@1.41.0) or pointing at a self-hosted instance with BROWSERLESS_API_URL. Both setups use the server name browserless, so replace the hosted entry with this one rather than adding both.
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"browserless": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@browserless.io/mcp"],
"env": {
"BROWSERLESS_TOKEN": "YOUR_API_TOKEN_HERE"
}
}
}
}
Check the connection
Open Customize in the sidebar and check browserless is toggled on. If it shows an error, open the Output panel and select MCP Logs.
FAQ & Troubleshooting
How do I keep my token out of mcp.json?
Cursor substitutes ${env:NAME} in url, headers, command, args, and env, so export BROWSERLESS_TOKEN before launching Cursor and reference it from the config. For the hosted server, set the header to "Bearer ${env:BROWSERLESS_TOKEN}", or drop the header and sign in with OAuth. For the local server, set "BROWSERLESS_TOKEN": "${env:BROWSERLESS_TOKEN}" in env. The local process has no OAuth sign-in, so it needs the token.
The server connects but every tool call returns 401 Unauthorized
The token is missing or wrong. Copy it again from your account dashboard and check the header reads Bearer followed by the token, with no quotes or trailing whitespace inside the value. If you used an environment variable, confirm it's set in the environment the client was launched from. GUI apps started from the dock or Start menu don't see variables exported in your shell profile.
The connection fails with an SSE error like Non-200 status code (400)
The hosted server speaks Streamable HTTP only and doesn't support the legacy SSE transport. Check the client entry is using its HTTP transport (see the config above), not an SSE one.