Load a skill explicitly:

{
  "method": "tools/call",
  "params": {
    "name": "browserless_skill",
    "arguments": { "id": "cookie-consent" },
  },
}

Residential proxy (browserless_agent)

Pass a top-level proxy object on browserless_agent to route the session through residential IPs. Use this when targets IP-block datacenter traffic.

{
  "method": "tools/call",
  "params": {
    "name": "browserless_agent",
    "arguments": {
      "method": "goto",
      "params": { "url": "https://example.com" },
      "proxy": {
        "proxy": "residential",
        "proxyCountry": "us",
        "proxySticky": true,
      },
    },
  },
}

| Field | Notes |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| proxy | "residential" — only value supported today. |
| proxyCountry | ISO-2 country code ("us", "de"). Auto-normalized to lowercase. Non-letter values are rejected. |
| proxyState | US state name with whitespace replaced by underscores ("new_york"). Paid-plan gated — non-eligible tokens get a 401. |
| proxyCity | City target. Paid/enterprise plan gated — non-eligible tokens get a 401. |
| proxySticky | Stable IP while the underlying WebSocket stays open. Reconnects (idle drop, network blip, browser crash) allocate a new sticky id and new IP. |
| proxyLocaleMatch | Match navigator locale to the proxy IP country. |
| proxyPreset | Named preset (e.g. "px_amazon01"). Available presets are plan-dependent — ask Browserless support for your list. |
| externalProxyServer | Bring-your-own upstream, e.g. http://user:pass@host:port. Must be http:// or https://. |

> Note: proxyCountry / proxyState / proxyCity / proxySticky / proxyLocaleMatch / proxyPreset require either proxy: "residential" or externalProxyServer to be set. The MCP rejects this combination at validation time; without it, the API would silently ignore them.

The proxy object is read once at session creation. To change it, call close and start a new session — the agent client keys sessions on the proxy fingerprint, so passing a different config will land on a fresh WebSocket.

Configuration

The server is hosted at https://mcp.browserless.io/mcp. Authenticate via headers (preferred) or a ?token= query parameter.

Installing via an AI agent? See install.md for agent-readable setup instructions.

Using headers (recommended for clients that support them):

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Using URL query parameters (for clients like Claude.ai custom connectors that only accept a URL):

https://mcp.browserless.io/mcp?token=your-token-here

To connect to a specific Browserless regional endpoint, add the x-browserless-api-url header or the browserlessUrl query parameter:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here",
        "x-browserless-api-url": "https://production-lon.browserless.io"
      }
    }
  }
}

https://mcp.browserless.io/mcp?token=your-token-here&browserlessUrl=https://production-lon.browserless.io

When both headers and query parameters are present, headers take precedence.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

VS Code

Add to your VS Code settings (settings.json):

{
  "mcp": {
    "servers": {
      "browserless": {
        "url": "https://mcp.browserless.io/mcp",
        "headers": {
          "Authorization": "Bearer your-token-here"
        }
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Self-Hosting

The server can also be run locally — useful for air-gapped deployments or pointing at a self-hosted Browserless instance. Clone this repo and build the Docker image:

docker build -f docker/Dockerfile -t browserless-mcp .
docker run \

  -e BROWSERLESS_TOKEN=your-token \

  -e BROWSERLESS_API_URL=https://your-browserless-instance.example.com \

  -p 8080:8080 \

  browserless-mcp

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

Self-hosted environment variables

| Variable | Required | Default | Description |
| ------------------------- | -------- | --------------------------------------- | -------------------------------------------------- |
| BROWSERLESS_TOKEN | Yes | — | Your Browserless API token |
| BROWSERLESS_API_URL | No | https://production-sfo.browserless.io | API endpoint (for self-hosted Browserless) |
| TRANSPORT | No | stdio | Transport type: stdio or httpStream |
| PORT | No | 8080 | HTTP server port (only for httpStream transport) |
| 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) |

MCP Resources

| Resource URI | Description |
| ------------------------ | ------------------------------- |
| browserless://api-docs | Smart scraper API documentation |
| browserless://status | Live service health status |

MCP Prompts

| Prompt | Description |
| ----------------- | ------------------------------------------- |
| scrape-url | Scrape a webpage and summarize its content |
| extract-content | Extract specific information from a webpage |

Development

npm install
npm run build
npm test
npm run coverage

Tests

The test suite uses Mocha with Chai and Sinon. Specs live alongside the code in test/ (test/lib/, test/tools/, test/prompts/, test/resources/, test/integration/) and run against the compiled output in build/.