fast-browser-mcp

fast-browser-mcp is a lightweight MCP server that adds persistent QA state on top of agent-browser.

It does not rebuild browser automation. Instead, it shells out to agent-browser commands and stores compact session state on disk so AI agents can reason over changes across multiple steps.

Features

• session-scoped storage (sessionId) instead of environment-scoped state
• persistent snapshots, diffs, errors, timeline, and QA report
• simple line-based diff optimized for AI readability
• file-based architecture only (no database, no workers, no polling)
• MCP-first tool interface for Cursor and other MCP clients

Why this project exists

AI-driven QA workflows lose context quickly between actions. This server keeps state per browser session so agents can:

• compare state before/after each action
• inspect recent console/network failures
• generate concise QA reports from deterministic stored artifacts

Requirements

• Node.js >=24 (required by agent-browser)
• npm

agent-browser does not need to be installed globally. This package will use a local/global agent-browser if available, and falls back to npx agent-browser@latest when needed.

Installation

Option A: Run from npm (after publish)

npx fast-browser-mcp

Option B: Install globally from GitHub (no npm registry publish required)

Direct npm i -g github:... can leave a broken symlink in global node_modules on some npm setups. Use the pack-then-install flow instead:

bash <(curl -fsSL https://raw.githubusercontent.com/donleqt/fast-browser-mcp/main/scripts/install-global.sh)

Or manually:

tmpdir=$(mktemp -d) && \
tarball=$(npm pack github:donleqt/fast-browser-mcp --pack-destination "$tmpdir" --silent) && \
npm i -g "$tmpdir/$tarball" && \
rm -rf "$tmpdir"

Then run:

fast-browser-mcp

Option C: Build from source

git clone https://github.com/donleqt/fast-browser-mcp.git
cd fast-browser-mcp
npm install
npm run build
node dist/index.js

Cursor MCP configuration

Add a stdio MCP server entry:

{
  "mcpServers": {
    "fast-browser-mcp": {
      "command": "npx",
      "args": ["fast-browser-mcp"]
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "fast-browser-mcp": {
      "command": "fast-browser-mcp",
      "args": []
    }
  }
}

Session model

• every browser flow is keyed by sessionId
• default sessionId is slug-safe and derived from URL
• duplicate derived session IDs are reused by default
• custom sessionId is supported

Examples:

• http://localhost:3000 -> localhost-3000
• https://app.example.com/dashboard -> app-example-com-dashboard

Storage layout

All artifacts are written under:

.fast-browser/
  sessions/
    {sessionId}/
      latest.md
      previous.md
      diff.md
      errors.md
      timeline.jsonl
      meta.json
      screenshot.png
      report.md

MCP tools

• fast_browser_open({ url, sessionId? })
• fast_browser_snapshot({ sessionId })
• fast_browser_diff({ sessionId })
• fast_browser_errors({ sessionId })
• fast_browser_act({ sessionId, action, ref?, value? })
• fast_browser_state({ sessionId })
• fast_browser_report({ sessionId })
• fast_browser_sessions({})

Quick example workflow

fast_browser_open({ url: "http://localhost:3000" })
fast_browser_state({ sessionId: "localhost-3000" })
fast_browser_act({ sessionId: "localhost-3000", action: "click", ref: "@e1" })
fast_browser_report({ sessionId: "localhost-3000" })

Architecture

• src/agentBrowser.ts: centralized CLI mapping and execution wrapper
• src/storage.ts: file-based session persistence
• src/tools.ts: MCP tool handlers and orchestration
• src/diff.ts: readable line-based diff
• src/report.ts: report generation

Scope and non-goals (MVP)

This project intentionally does not include:

• environment concepts (local/staging/prod)
• database or cloud sync
• authentication or multi-user orchestration
• web UI, React/Redux hooks, polling loops, background workers

Troubleshooting

• ENOTDIR or git dep preparation failed during global GitHub install
  • remove any broken global install: rm -f "$(npm root -g)/fast-browser-mcp"
  • reinstall using Option B above (pack-then-install), not npm i -g github:... directly
• agent-browser CLI not found...
  • ensure npx can run in your environment
  • optionally install agent-browser globally for faster startup (npm i -g agent-browser)
  • verify Node.js version is >=24
• session not found errors
  • run fast_browser_open first to create/reuse a session