Browserless MCP Server is the official MCP (Model Context Protocol) server for Browserless.io, designed to expose the Browserless Smart Scraper API to LLM clients such as Claude Desktop, Cursor, VS Code, and Windsurf. Through this server, AI agents can perform headless browser automation and web scraping tasks.
Key Capabilities
- Smart Scraper API Integration: Provides access to the Browserless Smart Scraper API, supporting web scraping and browser automation.
- Built-in Skill Library: The server comes with a built-in skill library, and agents can load recipes for handling complex page mechanisms on demand. Skills are automatically injected into browserless_agent responses when trigger conditions are met (for example, when the agent encounters a cookie banner), and can also be loaded manually via the browserless_skill tool.
- Proxy Support: A top-level proxy object can be passed on browserless_agent to route the session to datacenter or residential IPs. Datacenter proxies are cheaper per MB; residential proxies are less likely to be blocked. Note: geo, sticky, and locale options require a built-in proxy tier or externalProxyServer; proxyPreset requires proxy: "residential". MCP will reject unsupported combinations rather than letting the API silently ignore them. The proxy object is read once at session creation; to change it, call close and start a new session.
- Operating System Persona: Agent sessions can select a consistent operating system persona via top-level creation options. Set the persona options on the first call, then reuse the returned sessionId. The persona is fixed for the lifetime of that browser session, and it must be closed before selecting a different persona.
Usage
- Get an API Token: Get an API token from browserless.io (a free tier is available).
- Connect to the Hosted Server: Point the MCP client to the hosted server https://mcp.browserless.io/mcp。通过请求头（首选）或 ?token= query parameter for authentication.
- Using headers (recommended for clients that support headers): add the corresponding header in the configuration.
- Using a URL query parameter (for clients that only accept URLs, such as Claude.ai custom connectors): add the token parameter to the URL.
- Connect to a specific Browserless regional endpoint: add the x-browserless-api-url header or the browserlessUrl query parameter. When both a header and a query parameter are present, the header takes precedence.
- API URL overrides are limited to browserless.io and its subdomains, the configured BROWSERLESS_API_URL origin (same protocol, hostname, and port), and hosts listed in MCP_ALLOWED_API_URL_HOSTS. Paths are allowed, but credentials, query strings, and fragments are not.
- Client Configuration:
- Claude Desktop: add to claude_desktop_config.json.
- Cursor: add to Cursor MCP settings.
- VS Code: add to settings.json.
- Windsurf: add to the Windsurf MCP configuration.
- Run Locally: You can also run the server locally, suitable for air-gapped deployments or for pointing to a self-hosted Browserless instance. Clone the repository and build the Docker image, then point the MCP client to http://localhost:8080/mcp，使用相同的请求头/查询参数认证。
Use cases
- AI agent tasks that require browser automation, such as web scraping, form filling, and page interaction.
- Scraping tasks that handle complex page mechanisms (such as cookie banners and dynamic content loading).
- Scenarios that require proxy routing to avoid blocks or access specific geographic locations.
- Automation tasks that need to simulate a specific operating system environment.
Limitations
- Requires a valid Browserless API token.
- The proxy object is read once when the session is created; changes require recreating the session.
- The operating system persona is fixed for the session lifetime; changes require closing the session.
- API URL overrides have strict limitations and do not support arbitrary hosts.
- Some proxy options require specific configurations (for example, proxyPreset requires a residential proxy).
- Advanced features such as hosted OpenTelemetry and skill retrieval diagnostics require additional environment variable configuration.
- The test suite uses Mocha, Chai, and Sinon; running npm test does not require external services or BROWSERLESS_TOKEN.
Other information
- Official repository:https://github.com/browserless/browserless-mcp
- Installation instructions (for AI agents to read): see install.md in the repository.
- Security policy: see the security policy file in the repository.
- Get an API token:https://browserless.io
