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 Chrome DevTools Protocol. Shared across Cursor, Claude Code, Antigravity, and Zed.
Quickstart
1. 1-Step Setup (PyPI)
pip install agents-browser && agents-browser init
Scaffolds ~/.agents/browser/, autowires MCP configurations into your installed IDEs, and registers assistant skills.
2. Agent-Driven Setup (Zero Friction)
[!TIP] ๐ค Agent-Driven Setup (Zero Friction):
Simply tell your coding agent: "Install and set up agents-browser for me."
The agent installs the package, runsagents-browser init, and interacts with web applications, documentation, and search engines autonomously.
3. Source Checkout via vand
If you manage multi-repo checkouts with vand, agents-browser includes declarative lifecycle hooks in source.yml:
vand clone Lolaplex/agents-browser
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:
- 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) โ
โ 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 the browser to the specified URL |
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) |
MCP Tools Reference
| Tool | Parameters | Description |
|---|---|---|
browser_open |
url, new_tab (default: false) |
Navigate active tab or spawn a new tab. |
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_scroll |
direction ("down", "up", "top", "bottom"), amount |
Scroll the active page viewport. |
browser_go_back |
None | Navigate back in browser history. |
browser_reload |
ignore_cache (default: false) |
Reload active page (optional hard refresh). |
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. |
browser_search |
query, engine (default: "duckduckgo") |
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_scrape |
selector, mode ("text", "table", "links") |
Structured data extraction from CSS selector. |
browser_fill_form |
fields_json, submit_selector |
Batch fill form fields and submit in one call. |
browser_screenshot |
full_page (default: false) |
Capture PNG screenshot as base64. |
browser_evaluate |
script |
Execute arbitrary JavaScript in tab context. |
browser_tabs |
None | List active browser tabs with IDs and titles. |
browser_switch_tab |
tab_id |
Switch active tab focus. |
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
agents_browser-0.43.0.tar.gz
(30.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file agents_browser-0.43.0.tar.gz.
File metadata
- Download URL: agents_browser-0.43.0.tar.gz
- Upload date:
- Size: 30.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e5af88676359d2dab9946d254f0c6830fb2aed9cb3495a05eebe8c0427a8584f
|
|
| MD5 |
a0dc0d5cec54ab7c2f65f378b306d356
|
|
| BLAKE2b-256 |
e6df662fbae2bd3b1db03ee9cac36015c9d29d3343de25f8ceea19443c1fe85f
|
File details
Details for the file agents_browser-0.43.0-py3-none-any.whl.
File metadata
- Download URL: agents_browser-0.43.0-py3-none-any.whl
- Upload date:
- Size: 29.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3bad8d3a9fa9c4c3252f8880428b91202d8e11935da3ada083715356bdd58fbf
|
|
| MD5 |
47f6a1758c3e055785fe9aac87281be5
|
|
| BLAKE2b-256 |
f19e8d3c8034414256403481a73a0b0cf26830c53400132e521b3163459c9876
|
