Browserless MCP in Claude
Claude.ai, Claude Desktop, and Claude Code can all reach the hosted Browserless MCP server. Claude.ai and Claude Desktop add it as a custom connector with OAuth, while Claude Code takes a CLI command with OAuth or an API token header. Once it's connected, Claude 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
- Claude.ai, Claude Desktop, or Claude Code
Visual learner? Check out this video Claude’s #1 Headless Browser MCP for a step-by-step tutorial.
Connect to the hosted server
The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.
Claude.ai and Claude Desktop. Both add remote servers as custom connectors, which sync through your Claude account. Claude Desktop doesn't load remote servers from claude_desktop_config.json.
- Go to Customize > Connectors and click Add custom connector (on Pro and Max, click + Add first).
- Enter a name (for example
Browserless) andhttps://mcp.browserless.io/mcp, then click Continue. - Choose Sign in now to authorize with your Browserless account, then click Add.
To use an API token instead of OAuth, choose No sign-in and add an authorization request header with the value Bearer YOUR_API_TOKEN_HERE. Request headers are in beta and not every organization sees them. If yours doesn't, put the token in the URL instead:
https://mcp.browserless.io/mcp?token=YOUR_API_TOKEN_HERE
On Team and Enterprise plans, an Owner adds the connector under Organization settings > Connectors, and members then click Connect under Customize > Connectors.
Claude Code. Run in your terminal:
claude mcp add --transport http browserless https://mcp.browserless.io/mcp \
--header "Authorization: Bearer YOUR_API_TOKEN_HERE"
To sign in with OAuth instead, leave out --header and run /mcp in Claude Code to authenticate.
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.
Claude Desktop. Add to your claude_desktop_config.json:
{
"mcpServers": {
"browserless": {
"command": "npx",
"args": ["-y", "@browserless.io/mcp"],
"env": {
"BROWSERLESS_TOKEN": "YOUR_API_TOKEN_HERE"
}
}
}
}
Claude Code. Run in your terminal:
claude mcp add browserless --env BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE \
-- npx -y @browserless.io/mcp
Check the connection
In Claude.ai or Claude Desktop, click + in the chat input, choose Connectors, and toggle Browserless on for the conversation. In Claude Code, run /mcp and check browserless is listed as connected. For the local server in Claude Desktop, fully quit and restart the app after editing the config, then check Settings > Developer for its status. Logs are in ~/Library/Logs/Claude/mcp*.log on macOS.
FAQ & Troubleshooting
I added Browserless to claude_desktop_config.json as a URL and it never connects
Claude Desktop only reads local stdio servers (command, args, env) from that file. Add the hosted server as a custom connector instead, or use the local server config.
I can't find Request headers in the connector dialog
Request headers are in beta and only some organizations have them. Sign in with OAuth, or pass the token in the URL as ?token=YOUR_API_TOKEN_HERE.
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.