brosh

Brosh is exposed as an MCP server to integrate with AI tools and workflows. When run via the UVX runner, Brosh presents an MCP-compatible interface that can be queried to obtain scrolling screenshots, along with extracted text (in Markdown) and optional minified HTML for each captured frame. This makes it useful for AI contexts that require both visual and textual context of web pages, such as feeding Claude or other models with structured page content alongside its visual state. Use cases include visual regression testing pipelines, automated bug reporting, and content curation where you need synchronized image, text, and HTML data from dynamic pages.

To use the MCP server, start it with the UVX command provided in the installation instructions. Once running, you can send MCP requests to request captures for a given URL, optionally specifying a from_selector to begin scrolling from a particular element, viewport size, and scroll behavior. The server will return a structured payload containing per-frame data: the screenshot image, the extracted visible_text (in Markdown), and optionally visible_html (minified HTML) for the visible region. This enables AI-assisted understanding of page structure and content across long or dynamically loaded pages. You can configure output formats, scrolling steps, and other capture parameters to tailor the data for your model or testing workflow.

Prerequisites

• Python 3.8+ (recommended latest stable) installed on your system.
• Access to a terminal/command prompt.

Steps

1. Install the UVX runner (the MCP server launcher):

pip install uvx

2. Install the brosh package (the MCP server itself):

pip install brosh

3. Run the MCP server through UVX:

uvx brosh

Notes

• If you prefer a different package management flow, you can alternatively install brosh from source and run via uvx in the same way after satisfying dependencies.
• Ensure you have Playwright browsers installed if you plan to run local captures:

pip install brosh[playwright]
python -m playwright install

Tips and common issues:

• Environment variables: If you need to customize browser behavior or credentials, expose them via standard environment variables and access them within Brosh's configuration (e.g., VIEWPORT_WIDTH, VIEWPORT_HEIGHT, ZOOM_LEVEL).
• Large or complex pages: Adjust scroll_step and viewport to balance capture granularity with runtime. Brosh can extract text and HTML per visible frame; larger pages may generate more data.
• Debugging: If MCP requests fail, check that the UVX runner is correctly installed and that brosh is available in your Python environment. Verify network access to the server from the client tool.
• Output formats: Brosh supports PNG/JPEG/APNG; configure the desired output per frame as needed for your downstream AI or analysis pipeline.