Claude Code Plugin
The Browserless plugin for Claude Code gives Claude direct access to Browserless. It bundles an interactive browser agent with skills that scrape pages, search the web, map and crawl sites, export pages, run Lighthouse audits, and execute custom Puppeteer code, all from natural language.
- A Browserless API token (available in your account dashboard)
- Claude Code installed
Installation
Install the plugin from the Browserless marketplace inside Claude Code:
/plugin marketplace add browserless/claude-plugin
/plugin install browserless@browserless
To pull future updates, run:
/plugin marketplace update browserless
Manual install (local development)
If you're working on the plugin itself, clone the repo and point Claude Code at the plugin directory:
git clone https://github.com/browserless/claude-plugin.git
cd claude-plugin
claude --plugin-dir .
Authentication
Run the auth skill inside Claude Code:
/browserless:auth
This prompts you for your token and preferred API region (SFO, LON, AMS, or a custom URL for private deployments), saves the credentials to ~/.browserless/.env with 600 permissions, then validates the token with a test request to the /map endpoint. The Map API is only available on Cloud plans, so this check fails for self-hosted URLs even when your token works. Your credentials are still saved.
Alternatively, set the environment variable directly:
# On Windows:
# set BROWSERLESS_TOKEN=your-token-here
export BROWSERLESS_TOKEN=your-token-here
When you start a Claude Code session without a token configured, the plugin prints a reminder to run /browserless:auth.
Auth management
| Command | Description |
|---|---|
/browserless:auth | Interactive setup. Sets your token and region |
/browserless:auth status | Check if authentication is configured |
/browserless:auth clear | Remove saved credentials |
/browserless:auth region | Change the saved API region without re-entering your token. Requires credentials saved by /browserless:auth |
The REST skills load ~/.browserless/.env before every request, so a token and region saved there override a BROWSERLESS_TOKEN you've exported in your shell. The exported variable is only used when no saved file exists. To switch tokens, run /browserless:auth again, or run /browserless:auth clear if you'd rather manage the token through the environment variable.
API regions
| Region | URL |
|---|---|
| SFO (US West, default) | https://production-sfo.browserless.io |
| LON (Europe) | https://production-lon.browserless.io |
| AMS (Amsterdam) | https://production-ams.browserless.io |
| Custom | Any self-hosted or custom Browserless URL |
On a self-hosted URL, the Smart Scrape, Search, Map, and Crawl skills won't work because those APIs are Cloud-only. See open-source vs. Cloud for what self-hosted images support.
The region you pick applies to the REST skills only. /browserless:agent always connects through the hosted MCP server at mcp.browserless.io, which doesn't receive your region setting, so agent sessions run in the server's default region.
Skills
Once authenticated, all skills are available as slash commands:
/browserless:agent log into https://example.com and download my latest invoice
/browserless:smart-scrape https://example.com
/browserless:search what is browserless
/browserless:map https://example.com
/browserless:crawl crawl https://example.com up to 3 levels deep
/browserless:function click the login button on https://example.com
/browserless:export save https://example.com with all assets for offline viewing
/browserless:performance run a lighthouse audit on https://example.com
| Skill | Command | Description | Example prompt |
|---|---|---|---|
| Agent | /browserless:agent | Interactive, stateful browser session through the bundled MCP server. Navigates, clicks, types, logs in, handles CAPTCHAs and cookie banners, and uploads or downloads files across multi-step flows. | log into https://example.com and download my latest invoice |
| Smart Scrape | /browserless:smart-scrape | Scrape webpages with cascading strategies (HTTP fetch, proxy, headless browser, CAPTCHA solving). Returns markdown, HTML, screenshots, PDFs, or links. | summarize the main content of https://news.ycombinator.com |
| Search | /browserless:search | Search the web and optionally scrape result pages. Supports web, news, and image sources with time-based filtering and content categories. | find recent AI news en español from the last week |
| Map | /browserless:map | Discover and list all URLs on a website. Crawls sitemaps, pages, and subdomains with relevance-based search filtering. | save a list of all URLs on https://browserless.io in json format |
| Crawl | /browserless:crawl | Crawl a site from a seed URL, following links to a configurable depth and scraping every discovered page. Runs asynchronously and polls for results. | crawl https://docs.browserless.io up to 3 levels deep |
| Function | /browserless:function | Execute custom Puppeteer JavaScript in a cloud browser. Run your own automation scripts, interact with page elements, fill forms, and return structured data. | go to https://news.ycombinator.com and return the top 10 story titles as JSON |
| Export | /browserless:export | Export a webpage with its detected content type, optionally bundling all resources (CSS, JS, images) into a ZIP archive for offline use. | save https://example.com with all assets as a ZIP |
| Performance | /browserless:performance | Run a Lighthouse audit and get scores for performance, accessibility, best practices, SEO, and PWA. | audit the performance and accessibility of https://example.com |
Screenshots, PDFs, and file downloads don't have standalone skills. Ask /browserless:smart-scrape for the screenshot or pdf output format, and use /browserless:agent for downloads that sit behind a login or multi-step flow.
Choosing between agent and the REST skills
Use /browserless:agent when the task needs state across steps: logging in, clicking through pages, filling multi-page forms, or exploring a site. Sessions are one-shot by default. The browser stays open between calls only when the first call sets keepSessionAlive: true and later calls pass the returned sessionId, so ask Claude to keep the session alive for multi-step tasks. See session lifetime for details. The agent returns a page snapshot after every action, so Claude can decide the next step from what's actually on screen.
For one-shot work, the REST skills are faster and cheaper because most are a single request. Crawl is the exception: it starts an asynchronous job and polls for results. Use /browserless:smart-scrape to read a single page, /browserless:map or /browserless:crawl for site-wide work, and /browserless:function when you already know the exact Puppeteer steps.
MCP server
Installing the plugin also registers the hosted Browserless MCP server at https://mcp.browserless.io/mcp. It powers the agent skill and exposes the same capabilities as MCP tools:
| Tool | Description |
|---|---|
browserless_agent | Interactive browser session. Navigate, snapshot, click, type, and run multi-step automation |
browserless_smartscraper | Scrape a page as markdown, HTML, screenshot, PDF, or links |
browserless_crawl | Crawl a site to a configurable depth |
browserless_map | Discover all URLs on a site |
browserless_search | Web, news, and image search |
browserless_function | Run custom Puppeteer code |
browserless_export | Export a page with all assets |
browserless_performance | Run a Lighthouse audit |
The plugin passes the BROWSERLESS_TOKEN environment variable to the MCP server as a bearer token, so export it in your shell before you launch Claude Code. The MCP connection doesn't read ~/.browserless/.env or your region setting, and it won't authenticate if the variable is missing. See the browser agent docs for how the agent works.
API reference
Most skills map to a Browserless REST API endpoint. The agent skill is the exception: it runs through the bundled MCP server over a WebSocket session. Full API documentation is available in the REST APIs guide.
| Skill | Endpoint |
|---|---|
| Agent | MCP browserless_agent (WebSocket /chromium/agent) |
| Smart Scrape | POST /smart-scrape |
| Search | POST /search |
| Map | POST /map |
| Crawl | POST /crawl |
| Function | POST /function |
| Export | POST /export |
| Performance | POST /performance |
The Crawl API is currently in beta. Parameters and response shapes may change in future releases.
The Smart Scrape, Search, Map, and Crawl APIs are only available for Cloud plans, so
/browserless:smart-scrape,/browserless:search,/browserless:map, and/browserless:crawlwon't work against a self-hosted URL. Contact us for more information.
FAQ & Troubleshooting
How do I set or change my API token and region?
Run /browserless:auth inside Claude Code for interactive setup, or /browserless:auth region to change the region without re-entering your token. The region subcommand edits the saved file, so if you only exported BROWSERLESS_TOKEN, run /browserless:auth first. Credentials are stored in ~/.browserless/.env. The REST skills read that file before every request, so it overrides an exported BROWSERLESS_TOKEN. The region only affects the REST skills, not /browserless:agent. The agent uses only the exported BROWSERLESS_TOKEN, so to change its token, update that variable and restart Claude Code.
Which skill should I use to scrape a page?
Use /browserless:smart-scrape for most scraping tasks. It cascades through HTTP fetch, proxy, headless browser, and CAPTCHA solving strategies automatically, returning markdown, HTML, screenshots, PDFs, or links. To scrape many pages from one site, use /browserless:crawl instead.
How do I run custom automation beyond the built-in skills?
For interactive or multi-step tasks, use /browserless:agent. It decides each step from the live page, so you describe the goal instead of writing code. If you already know the exact steps, use /browserless:function to run custom Puppeteer JavaScript in a cloud browser and return structured data.
The browserless_agent tool isn't available. What's wrong?
The plugin's MCP server isn't connected. Run /mcp in Claude Code to check its status. The MCP server reads your token from the BROWSERLESS_TOKEN environment variable, not from ~/.browserless/.env, so export the variable in the shell you launch Claude Code from, then restart Claude Code.
Where did the /browserless:screenshot and /browserless:pdf skills go?
They were folded into /browserless:smart-scrape. Ask for a screenshot or PDF in your prompt and the skill requests the screenshot or pdf output format. Run /plugin marketplace update browserless if your installed version still lists the old skills.