.agents / browser
Ultra-fast, zero-Node Python CDP Browser MCP for AI coding agents.
Connects directly to your local Chrome, Edge, or Brave instance via native CDP. Headless by default.
Quickstart
1-Step Setup
pip install agents-browser && agents-browser init
Scaffolds ~/.agents/browser/, autowires MCP configurations into your installed IDEs, and registers assistant skills.
Source checkouts can also be installed and managed using vand.
Why .agents/browser?
Traditional browser automation MCPs (Playwright, Puppeteer) introduce massive friction:
- Download ~300MB Chromium binaries that hog disk space
- Spin up heavy Node.js runtimes that leave detached zombie processes
- Lack access to existing user sessions, cookies, and saved logins
- Dump 100k+ tokens of raw bloated HTML into LLM context windows
agents-browser connects directly to your installed browser via native CDP:
- Headless by Default: Silent
--headless=newbackground automation. Visible window only on explicit ask. - Zero Node.js / Zero 300MB Downloads: Pure lightweight Python (
FastMCP+websockets). - Indexed
@refInteractive Snapshots: Generates clean markdown with compact element references ([@1] Button: Login,[@2] Input: Search). - High-Level Built-in Tools: Web search, clean reader-mode extraction, table scraping, batch form filling, dropdown selection, viewport scrolling, in-page search, and network/DOM stability detection.
- Persistent Sessions (
~/.agents/browser): Preserves cookies, sessions, and saved logins across turns. - Universal Multi-IDE Auto-Config: Plugs into Cursor, Antigravity, Claude Desktop, and Zed in 1 second.
Architecture & Flow
┌─────────────────────────────────────────────────────────────┐
│ CODING AGENT / IDE │
│ Cursor · Antigravity · Claude Code · Windsurf · Zed │
└──────────────────────────────┬──────────────────────────────┘
│ FastMCP stdio
▼
┌─────────────────────────────────────────────────────────────┐
│ AGENTS-BROWSER CDP CLIENT │
│ Pure Python WebSocket · Port 9222 · Zero Node Runtime │
└──────────────────────────────┬──────────────────────────────┘
│ Direct CDP Commands
▼
┌─────────────────────────────────────────────────────────────┐
│ LOCAL BROWSER (Chrome / Edge / Brave) — headless=new │
│ Persistent Profile: ~/.agents/browser │
└──────────────┬───────────────────────────────┬──────────────┘
│ │
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ INDEXED SNAPSHOTS │ │ HIGH-LEVEL TOOLS │
│ [@1] Button: Sign In │ │ browser_search │
│ [@2] Input: Search │ │ browser_read_article │
│ Compact Interactive Tokens │ │ browser_fill_form │
└─────────────────────────────┘ └─────────────────────────────┘
CLI Reference
| Command | Purpose |
|---|---|
agents-browser init |
Plug & Play setup: auto-configures MCP across Cursor, Antigravity, Claude Desktop, Zed |
agents-browser open <URL> |
Navigates headless (add --visible for a desktop window) |
agents-browser system-open <URL> |
Opens URL in the OS default desktop browser |
agents-browser search "<query>" |
Performs a web search and prints top 10 organic markdown results |
agents-browser read |
Extracts active web page in clean Reader Mode |
agents-browser snapshot |
Captures text outline with compact indexed @ref interactive elements |
agents-browser screenshot --out <file> |
Captures a full or viewport PNG screenshot |
agents-browser serve |
Runs the FastMCP stdio server (default) |
Task-Adaptive Tool Architecture
agents-browser adapts dynamically to the developer's specific task without forcing a rigid workflow:
- Research & Reading:
browser_search,browser_read_article(distraction-free markdown),browser_extract_pdf,browser_fetch(fast HTTP using browser cookies). - Web Automation & Forms:
browser_snapshot(@refindexing) →browser_click,browser_type,browser_select,browser_fill_form,browser_scroll(target=...). - Data Scraping:
browser_scrape(mode='table'|'links'|'text'),browser_download. - Developer UI Testing & Dev Servers:
browser_audit(console errors & horizontal overflow detection),browser_inspect,browser_get_styles,browser_get_layout,browser_set_viewport. - Visual Proofs & Demos:
browser_screenshot(PNG),browser_record/browser_record_start+stop(MP4 video screencast via local ffmpeg).
MCP Tools Reference
| Category | Tool | Parameters | Description |
|---|---|---|---|
| Navigation | browser_open |
url, new_tab, visible |
Navigate headless by default; intercepts direct downloads & auto-dismisses cookie overlays. |
browser_system_open |
url |
Open URL in the user's personal desktop browser (Floorp, Firefox, Chrome, Edge). | |
browser_set_headless |
headless |
Toggle background headless mode (True = background, False = window). | |
browser_go_back |
None | Navigate back in browser history. | |
browser_reload |
ignore_cache |
Reload active page (optional hard refresh). | |
browser_tabs |
None | List active browser tabs with IDs, titles, and URLs. | |
browser_switch_tab |
tab_id |
Switch active tab focus. | |
| Research | browser_search |
query, engine |
Direct web search returning top organic results with Title, URL, and Snippet. |
browser_read_article |
None | Extracts clean article markdown, stripping ads, navbars, and banners. | |
browser_extract_pdf |
url_or_ref, save_path, max_pages |
Extracts PDF streams via Chrome PDF Viewer or Page.printToPDF with text preview. | |
browser_fetch |
url, method, headers, json_data, body |
Fast non-DOM HTTP/REST client using browser session cookies without rendering overhead. | |
| Automation | browser_snapshot |
None | Extract clean text outline with indexed @ref element IDs (@1, @2). |
browser_click |
target |
Click element by @ref (e.g. @1), CSS selector, or matching text. |
|
browser_type |
target, text, clear, press_enter |
Focus and type text into input/textarea. | |
browser_select |
target, value |
Select dropdown <select> option by text, value, or substring. |
|
browser_fill_form |
fields_json, submit_selector |
Batch fill form fields and submit in one call. | |
browser_scroll |
direction, amount, target |
Scroll page viewport or scroll target element smoothly into view. | |
browser_wait_stable |
timeout_ms, quiet_ms |
Wait for network requests (fetch/XHR) and DOM mutations to settle. | |
browser_find |
query, forward, match_case |
Fast in-page text search with match stats without dumping full page. | |
| Scraping | browser_scrape |
selector, mode ("table", "links", "text", "html") |
Structured data extraction from CSS selector into Markdown. |
browser_download |
ref_or_url, dest_path |
Intercept and monitor CDP downloads to controlled local directories. | |
| UI Testing | browser_audit |
None | Automated developer audit: console errors, horizontal layout overflow, broken media, failed requests. |
browser_inspect |
target |
Complete element card: tag, attributes, text snippet, geometry, typography, and box-model. | |
browser_get_styles |
target, properties |
Inspect computed CSS properties and declared CSS variables (--*). |
|
browser_get_layout |
target |
Inspect bounding rect (x, y, w, h), scroll metrics, and viewport visibility. |
|
browser_get_logs |
log_type, limit, clear |
Retrieve buffered console logs, uncaught exceptions, and failed HTTP network requests. | |
browser_set_viewport |
width, height, preset, mobile |
Set viewport dimensions or apply presets (mobile, tablet, desktop, fhd). |
|
browser_evaluate |
script |
Execute arbitrary JavaScript expression in tab context. | |
| Visuals | browser_screenshot |
full_page, path |
Capture PNG screenshot to ~/.agents/browser/screenshots/ (returns path + FastMCP Image). |
browser_record |
duration_sec, fps, path |
One-shot screen recording exported to MP4 video (or GIF) via local ffmpeg. | |
browser_record_start |
fps |
Begin interactive multi-step screen recording session. | |
browser_record_stop |
path |
Stop active recording session and encode captured frames into an MP4 video. |
Supported Ecosystem
- Claude Code: Bound via MCP server and
.agents/skills/browser-browse. - Google Antigravity: Integrated via
.gemini/configrules andagents-browserMCP. - Cursor: Automatically configures
.cursor/mcp.jsonand agent rules. - Zed: Configures
context_serversand mirrors assistant skills. - VS Code / Windsurf: Autowires Cline / Roo-Code MCP configuration.
Open ABI Specification
Detailed architectural specifications live in abi/:
abi/WHY.md— Rationale & why CDP beats heavy Node.js frameworks.abi/LAYOUT.md— Storage taxonomy in~/.agents/browser/.abi/MCP.md— Tool surface definitions and request/response contracts.abi/TOOLS.md— Exhaustive MCP tool reference & type signatures.abi/PLATFORM.md— Multi-platform browser binary & profile resolution.
Testing & Verification
Run the test suite:
python tests/run_all_tests.py
License
MIT License. See LICENSE for details.
Metadata
Release files for agents-browser 0.46.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agents_browser-0.46.0.tar.gz | 59.6 kB | Without provenance | Details for agents_browser-0.46.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_browser-0.46.0-py3-none-any.whl | Python 3 | none | any | Details for agents_browser-0.46.0-py3-none-any.whl |
Total release size: 116.8 kB
Release files / agents_browser-0.46.0.tar.gz
| Download URL | agents_browser-0.46.0.tar.gz |
|---|---|
| Size | 59.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
888d0e49e69fd7575eeb0a1a983ad5ecdf319fbdfb3a63ef9ff934d15ea631d6
|
|
BLAKE2b-256 checksum How to use checksums |
e1a7061be51cab819a4ef6b40f835c706eeb0a297415304fde9df2758af44c9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Release files / agents_browser-0.46.0-py3-none-any.whl
| Download URL | agents_browser-0.46.0-py3-none-any.whl |
|---|---|
| Size | 57.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce2a65dd44635557aee3113840522197896f343f670b5c52384dbef120d32cc6
|
|
BLAKE2b-256 checksum How to use checksums |
149f809cd220ca9fffc56e5797682ec829eab942364fd5719b4081a6dc7a5303
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Security for agents-browser 0.46.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.