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

Related MCP server: personal-kg-mcp

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 is installed as a dependency of this package, so consumers do not need a separate global agent-browser install.

Installation

Option A: Run from npm (after publish)

npx fast-browser-mcp

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

npm i -g "git+https://github.com/donleqt/fast-browser-mcp.git"

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

• agent-browser CLI not found...

  • ensure dependencies are installed (npm install)

  • verify Node.js version is >=24

• session not found errors

  • run fast_browser_open first to create/reuse a session