{"id":51333814,"url":"https://github.com/browserless/browserless-mcp","last_synced_at":"2026-07-02T01:03:24.324Z","repository":{"id":359397973,"uuid":"1162961198","full_name":"browserless/browserless-mcp","owner":"browserless","description":"Official MCP server for the Browserless.io ","archived":false,"fork":false,"pushed_at":"2026-07-01T11:28:00.000Z","size":1112,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T12:24:24.491Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browserless.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T22:49:15.000Z","updated_at":"2026-07-01T11:28:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/browserless/browserless-mcp","commit_stats":null,"previous_names":["browserless/browserless-mcp"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/browserless/browserless-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserless%2Fbrowserless-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserless%2Fbrowserless-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserless%2Fbrowserless-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserless%2Fbrowserless-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browserless","download_url":"https://codeload.github.com/browserless/browserless-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserless%2Fbrowserless-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35028649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-02T01:03:17.397Z","updated_at":"2026-07-02T01:03:24.318Z","avatar_url":"https://github.com/browserless.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Browserless MCP Server\n\n[![MCP Badge](https://lobehub.com/badge/mcp/browserless-browserless-mcp?style=for-the-badge)](https://lobehub.com/mcp/browserless-browserless-mcp)\n\nMCP (Model Context Protocol) server for [Browserless.io](https://browserless.io) — expose the Browserless smart scraper API to LLM clients like Claude Desktop, Cursor, VS Code, and Windsurf.\n\n## Quick Start\n\nGet an API token from [browserless.io](https://browserless.io) (free tier available), then point your MCP client at the hosted server:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp?token=your-token-here\"\n    }\n  }\n}\n```\n\nNo local install — see [Configuration](#configuration) for per-client snippets.\n\n## Tools\n\n| Tool                       | Description                                                                                                                                                                                                                                                                                                                                                                        |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `browserless_smartscraper` | Scrape a single webpage and return its content as markdown or HTML. Handles JavaScript-heavy pages and anti-bot measures automatically. For content across multiple pages, use `browserless_crawl`; to list a site's URLs, use `browserless_map`.                                                                                                                                  |\n| `browserless_search`       | Search the web using Browserless and optionally scrape each result. Supports web, news, and image search with geo-targeting and time filters.                                                                                                                                                                                                                                      |\n| `browserless_map`          | Discover and map all URLs on a website. Scans via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.                                                                                                                                                                                                  |\n| `browserless_crawl`        | Crawl a website and scrape every discovered page. Supports depth control, path filtering, sitemap strategies, and configurable scrape options. Returns scraped content and metadata for each page.                                                                                                                                                                                 |\n| `browserless_performance`  | Run Lighthouse audits on any URL. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets.                                                                                                                                                                                            |\n| `browserless_function`     | Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a `page` object and optional `context`; return `{ data, type }` to control the payload and Content-Type.                                                                                                                                                                                       |\n| `browserless_export`       | Export a webpage via the Browserless `/export` API. Fetches the URL and returns its native content (HTML, PDF, image, etc.) with automatic content-type detection.                                                                                                                                                                                                                 |\n| `browserless_agent`        | Drive a persistent browser session via a ReAct loop: snapshot the page, plan, batch interactions (click, type, scroll, evaluate, etc.), and re-snapshot. Uses ref-based selectors derived from snapshots, supports multi-tab workflows, screenshots, captcha solving, live URLs, and file upload/download (captured downloads auto-surface as handles; bytes never enter context). |\n| `browserless_skill`        | Load an on-demand recipe for a non-trivial page mechanic (shadow DOM, cookie consent, modals, captchas, dynamic content, snapshot misses, screenshots, tabs). Companion to `browserless_agent`.                                                                                                                                                                                    |\n\n## Skills\n\nThe server ships with a built-in library of **Skills** — on-demand recipes the agent can load to handle tricky page mechanics. Skills auto-inject into `browserless_agent` responses when their triggers fire (e.g. the agent hits a cookie banner), and can also be loaded manually via the `browserless_skill` tool.\n\n| Skill             | Source                                                         | Purpose                                                                           |\n| ----------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |\n| `shadow-dom`      | [src/skills/shadow-dom.md](src/skills/shadow-dom.md)           | Deep selectors and iframe targeting through shadow roots.                         |\n| `cookie-consent`  | [src/skills/cookie-consent.md](src/skills/cookie-consent.md)   | Vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, TrustArc, etc.).    |\n| `modals`          | [src/skills/modals.md](src/skills/modals.md)                   | Closing dialogs, alertdialogs, and overlay close-button heuristics.               |\n| `captchas`        | [src/skills/captchas.md](src/skills/captchas.md)               | Using the `solve` command, response semantics, and escalation paths (Cloud only). |\n| `dynamic-content` | [src/skills/dynamic-content.md](src/skills/dynamic-content.md) | Choosing the right `wait*` method for async/AJAX/SPA content.                     |\n| `snapshot-misses` | [src/skills/snapshot-misses.md](src/skills/snapshot-misses.md) | Handling truncated/empty snapshots and image-rendered content.                    |\n| `screenshots`     | [src/skills/screenshots.md](src/skills/screenshots.md)         | When to screenshot vs. snapshot, scope and format choices.                        |\n| `tabs`            | [src/skills/tabs.md](src/skills/tabs.md)                       | Multi-tab workflows and peek-without-switching via `targetId`.                    |\n\nLoad a skill explicitly:\n\n```jsonc\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"browserless_skill\",\n    \"arguments\": { \"id\": \"cookie-consent\" },\n  },\n}\n```\n\n### Residential proxy (`browserless_agent`)\n\nPass a top-level `proxy` object on `browserless_agent` to route the session through residential IPs. Use this when targets IP-block datacenter traffic.\n\n```jsonc\n{\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"browserless_agent\",\n    \"arguments\": {\n      \"method\": \"goto\",\n      \"params\": { \"url\": \"https://example.com\" },\n      \"proxy\": {\n        \"proxy\": \"residential\",\n        \"proxyCountry\": \"us\",\n        \"proxySticky\": true,\n      },\n    },\n  },\n}\n```\n\n| Field                 | Notes                                                                                                                                         |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `proxy`               | `\"residential\"` — only value supported today.                                                                                                 |\n| `proxyCountry`        | ISO-2 country code (`\"us\"`, `\"de\"`). Auto-normalized to lowercase. Non-letter values are rejected.                                            |\n| `proxyState`          | US state name with whitespace replaced by underscores (`\"new_york\"`). Paid-plan gated — non-eligible tokens get a 401.                        |\n| `proxyCity`           | City target. Paid/enterprise plan gated — non-eligible tokens get a 401.                                                                      |\n| `proxySticky`         | Stable IP while the underlying WebSocket stays open. Reconnects (idle drop, network blip, browser crash) allocate a new sticky id and new IP. |\n| `proxyLocaleMatch`    | Match `navigator` locale to the proxy IP country.                                                                                             |\n| `proxyPreset`         | Named preset (e.g. `\"px_amazon01\"`). Available presets are plan-dependent — ask Browserless support for your list.                            |\n| `externalProxyServer` | Bring-your-own upstream, e.g. `http://user:pass@host:port`. Must be `http://` or `https://`.                                                  |\n\n\u003e **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.\n\nThe `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.\n\n## Configuration\n\nThe server is hosted at `https://mcp.browserless.io/mcp`. Authenticate via headers (preferred) or a `?token=` query parameter.\n\nInstalling via an AI agent? See [install.md](install.md) for agent-readable setup instructions.\n\n**Using headers** (recommended for clients that support them):\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-token-here\"\n      }\n    }\n  }\n}\n```\n\n**Using URL query parameters** (for clients like Claude.ai custom connectors that only accept a URL):\n\n```text\nhttps://mcp.browserless.io/mcp?token=your-token-here\n```\n\nTo connect to a specific Browserless regional endpoint, add the `x-browserless-api-url` header or the `browserlessUrl` query parameter:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-token-here\",\n        \"x-browserless-api-url\": \"https://production-lon.browserless.io\"\n      }\n    }\n  }\n}\n```\n\n```text\nhttps://mcp.browserless.io/mcp?token=your-token-here\u0026browserlessUrl=https://production-lon.browserless.io\n```\n\nWhen both headers and query parameters are present, headers take precedence.\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp?token=your-token-here\"\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp?token=your-token-here\"\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to your VS Code settings (`settings.json`):\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"browserless\": {\n        \"url\": \"https://mcp.browserless.io/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Bearer your-token-here\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to your Windsurf MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"browserless\": {\n      \"url\": \"https://mcp.browserless.io/mcp?token=your-token-here\"\n    }\n  }\n}\n```\n\n## Self-Hosting\n\nThe 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:\n\n```bash\ndocker build -f docker/Dockerfile -t browserless-mcp .\n\ndocker run \\\n  -e BROWSERLESS_TOKEN=your-token \\\n  -e BROWSERLESS_API_URL=https://your-browserless-instance.example.com \\\n  -p 8080:8080 \\\n  browserless-mcp\n```\n\nThen point your MCP client at `http://localhost:8080/mcp` using the same header/query-parameter auth as above.\n\n### Self-hosted environment variables\n\n| Variable                  | Required | Default                                 | Description                                        |\n| ------------------------- | -------- | --------------------------------------- | -------------------------------------------------- |\n| `BROWSERLESS_TOKEN`       | Yes      | —                                       | Your Browserless API token                         |\n| `BROWSERLESS_API_URL`     | No       | `https://production-sfo.browserless.io` | API endpoint (for self-hosted Browserless)         |\n| `TRANSPORT`               | No       | `stdio`                                 | Transport type: `stdio` or `httpStream`            |\n| `PORT`                    | No       | `8080`                                  | HTTP server port (only for `httpStream` transport) |\n| `BROWSERLESS_TIMEOUT`     | No       | `30000`                                 | Request timeout in milliseconds                    |\n| `BROWSERLESS_MAX_RETRIES` | No       | `3`                                     | Max retry attempts for failed requests             |\n| `BROWSERLESS_CACHE_TTL`   | No       | `60000`                                 | Cache TTL in milliseconds (0 to disable)           |\n\n## MCP Resources\n\n| Resource URI             | Description                     |\n| ------------------------ | ------------------------------- |\n| `browserless://api-docs` | Smart scraper API documentation |\n| `browserless://status`   | Live service health status      |\n\n## MCP Prompts\n\n| Prompt            | Description                                 |\n| ----------------- | ------------------------------------------- |\n| `scrape-url`      | Scrape a webpage and summarize its content  |\n| `extract-content` | Extract specific information from a webpage |\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run coverage\n```\n\n### Tests\n\nThe test suite uses [Mocha](https://mochajs.org/) with [Chai](https://www.chaijs.com/) and [Sinon](https://sinonjs.org/). 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/`.\n\n- `npm test` — compiles TypeScript and runs every `*.spec.js` under `build/test/`. No external services or `BROWSERLESS_TOKEN` are required; the API client is stubbed.\n- `npm run coverage` — runs the suite under [c8](https://github.com/bcoe/c8) with the thresholds configured in `package.json` (lines ≥ 80%, branches ≥ 70%, functions ≥ 80%).\n\nTests run automatically on every pull request via the [Test workflow](.github/workflows/test.yml) on Node 24. PRs must keep the suite green before they can merge.\n\n## API Token\n\nGet your API token at [browserless.io](https://browserless.io). The token authenticates all requests to the Browserless API.\n\n## License\n\nSSPL-1.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserless%2Fbrowserless-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowserless%2Fbrowserless-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserless%2Fbrowserless-mcp/lists"}