Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BrowserBridge MCP navigate to news.ycombinator.com and extract the accessibility tree"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BrowserBridge MCP is a lightweight headless browser session bridge and Accessibility Object Model (AOM) inspector designed for AI coding assistants (Claude Desktop, Cursor, OpenAI Codex, LangGraph).
It enables agents to navigate web applications, extract semantic clean text, and interact with web pages without drowning the LLM context window in massive HTML blobs.
When autonomous AI agents interact with web pages:
Context Window Exhaustion: Dumping 2MB of raw HTML, scripts, CSS, and SVG icons into an LLM exhausts the token budget within 3 turns.
Brittle Selectors: Agents fail to find buttons when modern websites use dynamic, hashed class names (class="btn_3x9a_primary").
Zombie Memory Leaks: Unmanaged headless browsers leak memory on the host system when agents drop sessions without cleanup.
BrowserBridge solves this by converting web pages into a compact, token-efficient Accessibility Object Model (AOM) tree (~95% token reduction) and providing clean interaction primitives.
Related MCP server: Charlotte
🌐 Headless Navigation: Fetch and navigate web pages with automatic redirect handling.
🌳 Accessibility Tree (AOM) Extraction: Filters noisy DOMs into structured interactive nodes (buttons, links, textboxes) with stable @node identifiers.
🧹 Clean Text Extractor: Strips scripts, ads, and formatting for fast summarization.
⚡ Zero Browser Overhead: Pure Python runtime compatible with Claude Desktop and Cursor.
git clone https://github.com/johannschiffer/browserbridge-mcp.git
cd browserbridge-mcp
pip install -e .Add to your claude_desktop_config.json or Cursor MCP settings:
{
"mcpServers": {
"browserbridge": {
"command": "browserbridge",
"args": ["run"]
}
}
}# Inspect clean accessibility nodes of any website
browserbridge aom https://news.ycombinator.comTool | Parameters | Description |
|
| Navigates headless browser to destination URL |
|
| Extracts cleaned markdown text from page |
|
| Extracts compact interactive elements (AOM) |
|
| Simulates click on interactive element |
|
| Fills input or textarea field |
|
| Returns current URL, title, and response code |
Need enterprise-grade auditability, durable execution receipts, and browser pool sandboxing?
The BrowserBridge Pro Edition adds:
📜 Durable Action Receipts Engine: Generates cryptographic SHA-256 receipts for every web action, linking pre/post DOM hashes with visual state snapshots.
🛡️ Session Pool Manager con Anti-Zombie Auto-Cleanup: Manages multiple browser contexts with strict inactivity TTLs, preventing memory leaks on your host.
🎯 Visual Element Selector & Coordinate Resolver: Resolves robust CSS/XPath selectors and handles dynamic single-page applications (SPAs).
🐳 Production Docker & Compose: Containerized headless Chromium runtime ready for cloud execution.
🧪 100% Passing Pytest Suite.
👉 Get BrowserBridge Pro on Gumroad ($14.99 USD)
MIT © 2026 Johann Schiffer
Click an interactive element by CSS selector or target ID.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector or element name to click. | |
| session_id | No | Session identifier (default: 'default'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose what a click triggers (navigation, new tab, form submission), whether it waits for the element to become actionable, what happens if the selector matches nothing, or whether the action is reversible — critical context for an interaction tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with the action front-loaded and no filler. It is tight, though its brevity partly reflects under-specification rather than disciplined concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an interactive, side-effecting tool with no annotations and no output schema, the description omits the essentials: post-click behavior, waiting/auto-wait semantics, failure modes, and result reporting. An agent cannot predict the consequences of invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are documented and the baseline is 3. The description roughly restates the selector parameter, but its wording ('target ID') diverges from the schema's 'CSS selector or element name', adding mild ambiguity rather than new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Click an interactive element') with a mechanism (CSS selector / target ID), so the core action is unambiguous. However, it does nothing to distinguish this tool from siblings like fill_form_field or navigate_page, which also act on page elements, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no conditions for when to use this tool rather than navigate_page or fill_form_field, no prerequisites (page loaded? session active?), and no exclusions. The agent must infer the 'click vs fill vs navigate' split from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract interactive elements (buttons, links, inputs) as an Accessibility Object Model (AOM), reducing token cost by ~95%.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Session identifier (default: 'default'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose two useful traits: the output shape (AOM) and a rough cost profile (~95% token reduction vs. full DOM). It does not clarify that it is a non-mutating read, what happens on large or empty pages, or how output is bounded, so meaningful gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: the verb and resource come first, the output format and the token-cost benefit follow. No filler and nothing redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only extraction tool with one parameter and no output schema, the description covers what it returns and why it is cheap. However, it omits whether the result reflects the currently navigated page/state and how output scales, which an agent selecting it would want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one optional parameter and the schema documents it at 100% coverage, including its default, so the description need not repeat it. It adds no extra meaning about session_id semantics beyond the schema, which is the baseline expectation at full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb ('Extract') plus a specific resource ('interactive elements... as an Accessibility Object Model'), and the parenthetical enumeration (buttons, links, inputs) pins down what 'interactive' means. It distinguishes itself from extract_clean_text by focusing on interactive elements rather than text, though it never names that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the tool to call when it needs a compact map of clickable/fillable elements rather than page text. There is no explicit statement of when to prefer it over extract_clean_text or get_page_status, and no prerequisites (e.g. that a page must be loaded) are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract cleaned, semantic markdown text from current page, stripping scripts and clutter.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Session identifier (default: 'default'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output format (markdown) and that scripts/clutter are stripped, which is useful. However, it omits whether this requires an active session/page, whether it is read-only, and what happens on an empty or non-HTML page.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the action and the transformation front-loaded; no filler. It stops short of being exemplary only because there is no additional routing or prerequisite information to round it out.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read tool with one optional parameter and no output schema, the description covers the essentials. It still leaves open the required page/session state and whether navigation must precede extraction, which an agent would need when picking between this and the accessibility-tree sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter (session_id, default 'default') is documented in the schema. The description adds no parameter-level detail, but the baseline is 3 when the schema does the heavy lifting and there is little to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Extract') and resource ('cleaned, semantic markdown text from current page'), plus the transformation applied (stripping scripts and clutter). It implicitly distinguishes itself from extract_accessibility_tree by naming markdown text as the output, but does not name the sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description makes clear this is for pulling readable content off the current page, but it offers no when-to-use guidance, no prerequisites (e.g. a page must be loaded), and no comparison to the sibling extract_accessibility_tree.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enter text or value into a form input or textarea.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | Text value to insert. | |
| selector | Yes | CSS selector or input name. | |
| session_id | No | Session identifier (default: 'default'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: not whether existing content is overwritten or appended, whether input/change events are dispatched (critical for reactive form frameworks), what happens on a missing selector, or what is returned. Only the target element type is constrained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words and the action clearly leading. It is efficient, though its brevity is also the source of the coverage gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and 3 parameters, the description should cover prerequisites and side effects. It omits sequencing with navigate_page, event dispatch behavior, and overwrite semantics, leaving the agent under-informed about a state-changing interaction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so selector, value, and session_id are already documented in the schema. The description adds no format, syntax, or defaulting detail beyond that, which matches the baseline 3 for schema-documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (enter) and target resource (form input or textarea), which is concrete enough to separate it from click_element or navigate_page. It does not, however, explicitly contrast itself with any sibling, so an agent gets no routing help beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites (e.g. page must be navigated and the field may need to be focused or clicked first), and no mention of alternatives when the target is not a text input. The agent must infer all of this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect active session state, current URL, page title, and HTTP response code.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Session identifier (default: 'default'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It does disclose what information is inspected, which is helpful, but it does not explicitly state that the operation is read-only, has no side effects, or describe error conditions when no session is active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It efficiently states the key inspected values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-inspection tool with one optional parameter and no output schema, the description is mostly complete because it lists the returned fields. It could be slightly richer regarding return structure or behavior when no session exists, but the core information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage and documents the optional session_id with its default. The description adds no additional parameter meaning, so the schema carries the parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: inspect active session state, current URL, page title, and HTTP response code. It is clearly distinguishable from action-oriented siblings such as navigate_page and click_element, though it does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies the tool should be used when the agent needs to inspect current browser session status. However, it gives no explicit when-to-use guidance, prerequisites, or alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0click_elementextract_accessibility_treeextract_clean_textfill_form_fieldget_page_statusnavigate_pageScored across 6 tools
Each tool targets a distinct action: navigation, two extraction modes with clearly different outputs (markdown vs AOM), clicking, status inspection, and form filling. The two extraction tools are differentiated by description, so an agent can choose correctly.
All names use snake_case verb_noun format (navigate_page, extract_clean_text, click_element, etc.). Consistent and predictable.
Six tools is well-scoped for a focused headless browser bridge. Each tool covers a core operation without redundancy.
Core navigation, extraction, and basic interaction are covered, but common browser automation operations like scrolling, waiting for elements, taking screenshots, executing JavaScript, or handling multiple tabs are absent. These gaps may force workarounds for complex workflows.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Headless browser primitives for AI agents when sites need real JS rendering.
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
