Headless Browser Tool

A headless browser control tool that provides an MCP (Model Context Protocol) server with tools to control a headless browser using Capybara and Selenium. Features multi-session support, session persistence, and both HTTP and stdio communication modes.

Features

• Headless Chrome browser automation - Full browser control via Selenium WebDriver
• MCP server with 40+ browser control tools - Comprehensive API for browser interactions
• Multi-session support - Isolated browser sessions for each client
• Session persistence - Sessions survive server restarts with cookies and state preservation
• Two server modes - HTTP server mode and stdio mode for different integration patterns
• Smart screenshot tools - With annotations, highlighting, and visual diff capabilities
• AI-assisted tools - Auto-narration and intelligent page analysis
• Comprehensive logging - Separate log files for stdio mode to avoid protocol interference
• Structured responses - All tools return rich, structured data instead of simple strings
• Smart element selectors - Tools returning multiple elements include selectors for each

Installation

Add this line to your application's Gemfile:

gem 'headless_browser_tool'

And then execute:

bundle install

Or install it yourself as:

gem install headless_browser_tool

Prerequisites

You need to have Chrome/Chromium browser installed on your system. The gem will use Chrome in headless mode by default.

Usage

Command Line Interface

The hbt command provides three main commands:

hbt start - Start HTTP Server Mode

Starts the MCP server as an HTTP server with SSE (Server-Sent Events) support:

hbt start [OPTIONS]

Options:

• --port PORT - Port for the MCP server (default: 4567)
• --headless / --no-headless - Run browser in headless mode (default: true)
• --single-session - Use single shared browser session instead of multi-session mode
• --session-id SESSION_ID - Enable session persistence for single session mode (requires --single-session)
• --show-headers - Show HTTP request headers for debugging session issues

Examples:

# Start with default settings (multi-session, headless, port 4567)
hbt start

# Start in non-headless mode for debugging
hbt start --no-headless

# Start in single session mode (legacy compatibility)
hbt start --single-session

# Start in single session mode with persistence
hbt start --single-session --session-id my-app-session

# Start with request header logging
hbt start --show-headers

hbt stdio - Start Stdio Server Mode

Starts the MCP server in stdio mode for direct integration with tools that spawn subprocesses:

hbt stdio [OPTIONS]

Options:

• --headless / --no-headless - Run browser in headless mode (default: true)

Notes:

• Always runs in single-session mode
• Logs to .hbt/logs/PID.log instead of stdout to avoid interfering with MCP protocol
• Ideal for editor integrations and tools that communicate via stdin/stdout
• Supports optional session persistence via HBT_SESSION_ID environment variable

Session Persistence in Stdio Mode:

You can enable session persistence by setting the HBT_SESSION_ID environment variable:

# First run - creates and saves session
HBT_SESSION_ID=my-editor-session hbt stdio

# Later run - restores previous session state
HBT_SESSION_ID=my-editor-session hbt stdio

When HBT_SESSION_ID is set:

• Session state is saved to .hbt/sessions/{session_id}.json on exit
• On startup, if the session file exists, it restores:
  • Current URL
  • Cookies
  • localStorage
  • sessionStorage
  • Window size

This is useful for editor integrations that want to maintain browser state across multiple tool invocations.

Examples:

# Start in stdio mode (headless by default, no persistence)
hbt stdio

# Start with session persistence
HBT_SESSION_ID=vsc

... [View full README on GitHub](https://github.com/parruda/headless-browser-tool#readme)