Browserless MCP Server

The Browserless MCP server gives AI assistants full browser automation through the Model Context Protocol. Connect any MCP-compatible client to scrape, search, crawl, audit, and run custom browser code with no infrastructure to manage.

Prerequisites

• A Browserless account - either an API token from your account dashboard, or OAuth sign-in
• An MCP-compatible client (Claude Desktop, Cursor, VS Code, Windsurf, etc.)

Hosted Server

Browserless provides a hosted MCP server ready to use:

https://mcp.browserless.io/mcp

No installation or environment variables required. See Authentication for how to connect.

Authentication

OAuth

OAuth connects through your Browserless account, so you don't need to copy or manage an API token. When you connect from a supported client such as Claude Desktop or Cursor, the client opens a browser window for you to sign in.

OAuth is enabled on the hosted server at https://mcp.browserless.io/mcp with no extra configuration needed.

API Token

API token authentication works with clients that accept custom headers or URL query parameters. Copy your token from the account dashboard, then pass it using one of these methods:

Header (recommended): Authorization: Bearer YOUR_API_TOKEN_HERE

Query parameter: ?token=YOUR_API_TOKEN_HERE (for URL-only clients such as Claude.ai custom connectors)

If a request carries more than one method, the server uses an API token in the Authorization header first, then the token query parameter, then an OAuth token in the Authorization header.

Client Setup

Pick your client to see its config for the hosted server. Each client also has a full guide covering local setup, how to check the connection, and client-specific troubleshooting.

Client

Full Claude guide →

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.

1. Go to Customize > Connectors and click Add custom connector (on Pro and Max, click + Add first).
2. Enter a name (for example Browserless) and https://mcp.browserless.io/mcp, then click Continue.
3. 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.

Run Locally

Requirements

Node.js 24 or newer.

Prefer not to use the hosted server? The MCP server is published to npm as @browserless.io/mcp, so you can run it locally with npx. No cloning, building, or Docker required. This is useful for pinning a specific server version (for example npx -y @browserless.io/mcp@1.41.0) or pointing at a self-hosted Browserless instance, including fully air-gapped setups, but only when that self-hosted instance also runs inside the isolated network.

Running locally still calls the Browserless cloud (or your self-hosted instance) for the actual browser work. Only the MCP server process runs on your machine.

stdio (MCP clients)

Local clients start the server as a subprocess over stdio, which is the default mode. Most clients take an entry in this shape:

{
  "mcpServers": {
    "browserless": {
      "command": "npx",
      "args": ["-y", "@browserless.io/mcp"],
      "env": {
        "BROWSERLESS_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

The top-level key and file location vary by client. VS Code uses servers, Zed uses context_servers, Amp uses amp.mcpServers, and Codex and Grok Build use TOML. Each client guide has the exact local config. CLI clients can add it in one command:

claude mcp add browserless --env BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE \
  -- npx -y @browserless.io/mcp

HTTP (httpStream)

To run the server as a long-lived HTTP endpoint (for example to share one instance across clients) set TRANSPORT=httpStream:

TRANSPORT=httpStream PORT=8080 BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE \
  npx -y @browserless.io/mcp

Then point your MCP client at http://localhost:8080/mcp, using the same header or query-parameter auth as the hosted server.

Environment variables

Variable	Required	Default	Description
BROWSERLESS_TOKEN	Yes	—	Your Browserless API token
BROWSERLESS_API_URL	No	https://production-sfo.browserless.io	API endpoint (set this to point at a self-hosted instance or a different region)
TRANSPORT	No	stdio	Transport type: stdio or httpStream
PORT	No	8080	HTTP server port (only used with httpStream)
BROWSERLESS_TIMEOUT	No	30000	Request timeout in milliseconds
BROWSERLESS_MAX_RETRIES	No	3	Max retry attempts for failed requests
BROWSERLESS_CACHE_TTL	No	60000	Cache TTL in milliseconds (0 to disable)

Regional Endpoints

By default, the hosted MCP server connects to the US West (San Francisco) Browserless region. To use a different region, pass the endpoint as a header or query parameter:

Region	Endpoint
US West — San Francisco (default)	https://production-sfo.browserless.io
Europe — London	https://production-lon.browserless.io
Europe — Amsterdam	https://production-ams.browserless.io

Using the x-browserless-api-url header (for clients that support headers):

{
  "mcpServers": {
    "browserless": {
      "type": "http",
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE",
        "x-browserless-api-url": "https://production-sfo.browserless.io"
      }
    }
  }
}

Using the browserlessUrl query parameter (for URL-only clients like Claude.ai):

https://mcp.browserless.io/mcp?token=YOUR_API_TOKEN_HERE&browserlessUrl=https://production-sfo.browserless.io

Tools

The MCP server exposes fourteen tools to your AI assistant, split across three reference pages:

Browser Agent

A single stateful tool, browserless_agent, that can drive a browser session across turns. In MCP server v1.33.0+, sessions are one-shot by default. For multi-step work, set keepSessionAlive: true on the first call, then echo the returned sessionId on later calls. The model can then navigate, snapshot, click, type, and react within one browser context. See session lifetime and examples.

REST API Tools

Eight stateless tools: one call in, one result out. Seven wrap individual Browserless REST endpoints; the eighth, browserless_skill, loads on-demand agent guidance:

Tool	Purpose
browserless_smartscraper	Scrape any URL with cascading strategies (HTTP → proxy → headless → CAPTCHA solving)
browserless_function	Run custom Puppeteer JavaScript on the Browserless cloud
browserless_export	Export a page as HTML, PDF, image, or full offline ZIP
browserless_search	Web/news/image search with optional scraping of each result
browserless_map	Discover all URLs on a site via sitemap and link extraction
browserless_performance	Run a Lighthouse audit (accessibility, performance, SEO, PWA, best practices)
browserless_crawl	Crawl a site from a seed URL and scrape every discovered page
browserless_skill	Load an on-demand agent skill or discover site-specific recipes

Account Tools

Five read-only tools that report on the account behind your API token. None of them changes account state or returns API token values:

Tool	Purpose
browserless_account	Plan, unit balance, billing period, and API key names
browserless_usage	Request counts and billed units for the account or specific keys
browserless_logs	Browserless-side request logs for diagnosing failed runs
browserless_sessions	Running browsers, persistent sessions, replays, and 1Password integrations
browserless_profiles	Saved authentication profiles other tools reuse by name

FAQ & Troubleshooting

My client fails with an SSE error like Non-200 status code (400)

The hosted server speaks the Streamable HTTP transport only; it doesn't support the legacy SSE transport. In clients that let you pick (n8n's MCP Client node, some SDKs), select Streamable HTTP rather than SSE, point it at https://mcp.browserless.io/mcp, and authenticate with an Authorization: Bearer YOUR_API_TOKEN_HERE header or the ?token= query parameter.

How much do MCP sessions cost?

Each MCP tool call opens a browser session that consumes units based on session time, plus proxy traffic and CAPTCHA solving if used. See Unit Consumption for the full breakdown.

Next steps

REST API Tools

the eight stateless MCP tools

Browser Agent

the stateful, multi-turn browserless_agent tool