browser-mcp-server

Browser automation and web scraping MCP server powered by headless Chromium.

Standalone binary that exposes 27 browser automation and web scraping tools over MCP (Model Context Protocol) via stdio or HTTP transport using JSON-RPC 2.0.

Features

• 20 browser session tools — open, screenshot, click, fill, select, wait_for, evaluate, scroll, get_text, inspect, get_attribute, go_back, go_forward, close, press_key, hover, reload, get_cookies, set_cookie, clear_cookies
• 3 HTTP tools — url_read (HTML to Markdown), url_read_raw, url_search (Brave/DuckDuckGo)
• 4 scraper tools — fetch (HTTP-first with browser fallback), read_markdown (Readability), probe, submit_form
• Stealth mode — CDP patches, User-Agent spoofing, navigator overrides, plugin emulation
• Session management — multiple concurrent browser sessions with auto-cleanup
• Dual transport — stdio (default) or HTTP mode via --transport flag
• HTTP transport — MCP Streamable HTTP with Bearer token authentication and session management

Architecture

Single crate, seven source modules:

Module	Responsibility
src/main.rs	CLI parsing (clap), entry point, transport selection, tool definitions, tool dispatch
src/mcp.rs	JSON-RPC 2.0 types, MCP tool result helpers, async stdio loop, async dispatch
src/http.rs	HTTP transport: axum server, Bearer auth, MCP HTTP session management
src/browser.rs	Chromium lifecycle, stealth patches, 20 browser tool handlers, session cleanup
src/search.rs	url_read, url_read_raw, url_search (Brave/DDG)
src/content.rs	read_markdown (Readability), probe, submit_form
src/fetch.rs	fetch (HTTP-first, browser fallback)

CLI Arguments

browser-mcp-server [OPTIONS]

Options:
  --transport <MODE>             Transport mode: stdio or http [default: stdio]
  --host <HOST>                  Host to bind HTTP server [default: 127.0.0.1]
  --port <PORT>                  Port for HTTP server [default: 8080]
  --auth <TOKEN>                 Bearer token for HTTP authentication (optional)
  --chrome-path <PATH>           Path to Chrome/Chromium binary (auto-detected if not set)
  --headless                     Run in headless mode [default: true]
  --max-sessions <N>             Max concurrent browser sessions [default: 5]
  --session-timeout-secs <N>     Session auto-close after inactivity [default: 300]
  --page-load-timeout-ms <N>     Per-navigation timeout [default: 60000]
  --content-timeout-ms <N>       Page content extraction timeout [default: 60000]
  --max-content-bytes <N>        Max HTML size before truncation [default: 1000000]
  --no-sandbox                   Disable Chrome sandbox (required in Docker)
  --data-dir <PATH>              Data directory for screenshots & Chrome profile
  --version                      Print version and exit

Build

Prerequisites

• Rust toolchain (stable)
• Chromium or Google Chrome (runtime dependency)

Build

cargo build --release

With Nix

nix develop    # dev shell with all dependencies
nix build      # build the package

Runtime Dependencies

• Chromium or Google Chrome — auto-detected, or set --chrome-path

Rust Dependencies

Crate	Purpose
chromiumoxide	Headless Chrome/Chromium via CDP
htmd	HTML to Markdown conversion
readability	Mozilla Readability content extraction
reqwest	HTTP client for lightweight tools
futures	Stream handling for Chrome events
url	URL parsing
dirs	Default data directory
clap	CLI argument parsing
serde, serde_json	JSON serialization for MCP protocol
tracing, tracing-subscriber	Structured logging to stderr
axum	HTTP server framework for MCP HTTP transport
tokio	Async runtime
uuid	Session ID generation (UUID v4)

MCP Protocol

The server supports two transport modes:

• stdio (defau

... View full README on GitHub