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