Apex Browser

Local multi-session browser MCP for real Chrome, Chromium, WebKit, and real Safari, plus attach to an already-running Chrome session without moving the work into a cloud browser.

Release posture: npm package @apexradius/browser-mcp, version 1.0.0 from package.json.

Choose your path

You are...	Start here	Then
Running the daemon or stdio server	docs/start-here.md	Quick start below
Auditing browser routing or attach behavior	docs/architecture.md	src/manager.js
Reviewing the MCP tool surface	src/server.js	src/index.js

Architecture

flowchart TD
  U[AI operator] --> C[MCP client]
  C --> T[stdio or HTTP transport]
  T --> S[MCP server]
  S --> M[BrowserManager]
  M --> P[SessionPool]
  M --> F[SafariLane]
  P --> B[Chrome Chromium WebKit sessions]
  P --> D[Attached Chrome via CDP]
  F --> R[Real Safari.app session]

Request flow

flowchart TD
  A[Operator opens or attaches a browser session] --> B[Selected MCP tool]
  B --> C{New session or attach?}
  C -- new --> D[BrowserManager creates session]
  C -- attach --> E[Connect to CDP endpoint]
  D --> F[Session stored in pool]
  E --> F
  F --> G[Subsequent navigate snapshot click type evaluate tools]
  G --> H[Return text or screenshot path to MCP client]

Quick start

1. Install dependencies and browser engines.

npm install
npx playwright install chromium webkit

2. Start the shared HTTP daemon.

APEX_BROWSER_TRANSPORT=http node src/index.js

3. Register it in your MCP client.

{
  "mcpServers": {
    "apex-browser": {
      "type": "http",
      "url": "http://127.0.0.1:3010/mcp"
    }
  }
}

Available tools

Tool group	Tools	Purpose
Session lifecycle	browser_new_session, browser_attach, browser_list_sessions, browser_close_session	Open, adopt, inspect, and close sessions
Navigation and state	browser_navigate, browser_snapshot	Load pages and capture indexed interactive refs
Interaction	browser_click, browser_type, browser_evaluate	Drive page interactions and execute page JS
Artifacts	browser_screenshot	Save a PNG and return its path

Runtime proof

Claim	Proof
Package entry point is stable	"apex-browser-mcp": "src/index.js" in package.json
HTTP and stdio transports are both first-class	Transport selection in src/index.js
Session routing is engine-aware	BrowserManager in src/manager.js
Tool registration is centralized	buildServer() in src/server.js

Repo map

Path	Purpose
src/index.js	Process entry point, transport selection, HTTP daemon
src/server.js	MCP tool registration and request handlers
src/manager.js	Unified routing across SessionPool and SafariLane
src/pool.js	Multi-session Playwright and CDP attach backend
src/safari.js	Real Safari.app lane
docs/start-here.md	Setup, env, validation, common failures
docs/architecture.md	Component map and runtime lifecycle

Validation

Check	Command
Core regression suite	npm test
Attached-Chrome concurrency	node test/attach-concurrent.js
README/docs links stay local	rg '\\]\\(([^)]+\\.md)\\)' README.md docs/

License

MIT