cursor-browser-cli

Drive Cursor IDE’s built-in Browser Tab from any CLI agent or shell — Grok Build, Claude Code, Codex, OpenCode, or plain terminal — without leaving Cursor and without spinning up a separate Chrome/Playwright stack.

Stay in a long chat in Cursor’s integrated terminal. Navigate, take accessibility snapshots with refs, click/type/fill by ref, wait for page state, lock the tab, screenshot, and inspect console/network/DOM — all on the same Browser Tab you already see in the IDE.

Grok Build · Claude Code · Codex · OpenCode · shell
              │
              │  CLI  (cursor-browser)
              │  or MCP stdio  (mcp/server.mjs)
              ▼
     localhost HTTP  127.0.0.1:<port>
              │
              ▼
   Cursor extension (workspace host)
              │  cursor.browserView.*
              ▼
     Cursor Browser Tab  (this project window)

Why this exists

The problem

Cursor ships Browser Automation for its own Cursor Agent (chat/composer with built-in browser tools). That is great when you stay inside Cursor Agent.

Many people do not stay there. A common workflow is:

1. Open a project in Cursor

2. Run Grok Build, Claude Code, Codex, or another CLI agent in the integrated terminal

3. Still want to use the in-IDE Browser Tab for UI checks, local apps, auth flows, visual verification, etc.

Those CLI agents cannot call Cursor Agent’s built-in browser tools. Without something else, you end up:

• Opening extra Chrome windows and tabs

• Re-explaining context across tools

• Running a separate Playwright/CDP stack just to “see” the app

• Or bouncing back into Cursor Agent only for browser steps

That breaks the flow: you wanted one IDE window, one Browser Tab, and multiple agents that can share it.

The solution

cursor-browser-cli is a small local stack that lets any agent (or script) control Cursor’s Browser Tab the same way Cursor Agent does — via:

You keep working in the CLI agent. The Browser Tab stays inside Cursor. No second browser product required for day-to-day agent work.

What this is not

This project targets one job: multi-agent access to Cursor’s Browser Tab from CLI/MCP while you work inside Cursor.

Related MCP server: @nimbus21.ai/chrome-devtools-mcp

Features

Multi-agent by design

• Same Browser Tab for Grok Build, Claude Code, Codex, OpenCode, shell scripts, and humans

• CLI and MCP share the same extension HTTP API

• Workspace routing so multiple Cursor windows do not step on each other

• Optional skill files for Grok / Claude / agents that load SKILL.md

Agent-grade interaction (ref model)

• Accessibility snapshot with refs (e1, e5, …) — YAML-style tree agents can read and act on

• Click / type / fill / hover by ref (CSS selector fallback where supported)

• wait for URL substring, visible text, ref, or CSS selector (reduces agent races)

• Lock / unlock the tab during automation so accidental human input does not fight the agent

• Resize viewport

• open / nav return a snapshot by default so the next step has fresh refs

Fast, CLI-first

• Single binary-style script on your PATH: cursor-browser

• Low overhead: Node built-ins only, loopback HTTP, no runtime npm deps

• Multi-window: --workspace <folder> or match cwd

• Single-tab policy: reuse one tab; close extras for predictable automation

Under the hood (debug like DevTools)

• Screenshot (PNG path; MCP can return image content when available)

• inspect — meta, counts, headings, links, inputs, body text

• console / network via Cursor getConsoleLogs / getNetworkRequests

• eval — run page JavaScript

Local and contained

• Listens on 127.0.0.1 only

• Per-window port (default base 17373, auto-increments if busy)

• State under ~/.cursor-browser-cli/

• Status bar shows project :port so you know which window is listening

Requirements

• Cursor IDE with Browser Tab / cursor.browserView.* APIs available

• Node.js ≥ 18 (CLI + MCP; no production npm dependencies)

• macOS / Linux / Windows (where Cursor runs)

Install (recommended: npm)

npm install -g cursor-browser-cli

That installs:

If the extension step was skipped (e.g. npm i --ignore-scripts), run:

cursor-browser setup

Then reload each Cursor window you use:

Cmd+Shift+P (or Ctrl+Shift+P) → Developer: Reload Window

Confirm the status bar shows something like your-project :17375, then:

cursor-browser windows
cursor-browser --workspace <project-folder> open https://example.com
cursor-browser --workspace <project-folder> snapshot

Skip automatic setup

CURSOR_BROWSER_SKIP_SETUP=1 npm install -g cursor-browser-cli
cursor-browser setup   # when ready

From source (optional)

git clone https://github.com/bcharleson/cursor-browser-cli.git
cd cursor-browser-cli
npm install          # runs setup
# or: ./scripts/install.sh

Extension commands (inside Cursor)

Settings

Quick start (agent loop)

This is the loop CLI agents should follow:

export WS=my-app   # folder name of the Cursor workspace

# 1) One clean tab + navigate → snapshot with [ref=e…] printed
cursor-browser --workspace $WS close
cursor-browser --workspace $WS open http://localhost:3000

# 2) Interact by ref from the snapshot
cursor-browser --workspace $WS click e5
cursor-browser --workspace $WS fill e3 "hello"
cursor-browser --workspace $WS press Enter

# 3) Wait for navigation / UI (avoid races)
cursor-browser --workspace $WS wait --url /results --timeout 15000
cursor-browser --workspace $WS wait --text "Success"

# 4) Visual / debug
cursor-browser --workspace $WS screenshot /tmp/out.png
cursor-browser --workspace $WS inspect
cursor-browser --workspace $WS console

Rules of thumb

1. Take a fresh snapshot after navigation or large DOM changes before using refs.

2. Prefer ref (e12) over CSS when the snapshot provides one.

3. Prefer open / nav (they return snapshots) over bare navigate without a follow-up snap.

4. Use wait after clicks that change URL or content.

5. Use close if extra tabs pile up; keep one tab for reliability.

6. With multiple Cursor windows, always pass --workspace.

CLI reference

cursor-browser [--workspace NAME|PATH] [--port N] <command> [args]

Global flags

Environment variables

Legacy env names from earlier package renames may still be read by clients for compatibility.

Routing commands

Tabs and navigation

Interaction (prefer refs from snapshot)

Wait, viewport, capture, debug

wait flags

Examples:

cursor-browser --workspace my-app wait --url /dashboard --timeout 15000
cursor-browser --workspace my-app wait --text "Welcome"
cursor-browser --workspace my-app wait --ref e12
cursor-browser --workspace my-app wait --selector "button.save"

Multi-window routing order

When you have several Cursor projects open, the CLI picks a target in this order:

1. --port / CURSOR_BROWSER_CLI_PORT

2. --workspace / CURSOR_BROWSER_WORKSPACE

3. Match current cwd to a registered workspace folder

4. Process discovery fallback (lsof on loopback ports in the 173xx range)

5. Single open instance

cursor-browser windows
cursor-browser --workspace af-exec-travel whoami
cursor-browser --workspace af-exec-travel open http://localhost:3000

MCP server

Stdio MCP server for agents that prefer tools over shelling out.

After npm install -g cursor-browser-cli, the bin cursor-browser-mcp is on your PATH.

Register

# Grok Build
grok mcp add cursor-browser -- cursor-browser-mcp

# Claude Code
claude mcp add cursor-browser -- cursor-browser-mcp

Any stdio MCP client:

{
  "mcpServers": {
    "cursor-browser": {
      "command": "cursor-browser-mcp"
    }
  }
}

Fallback (from a clone or if the bin is not on PATH):

{
  "mcpServers": {
    "cursor-browser": {
      "command": "node",
      "args": ["/absolute/path/to/cursor-browser-cli/mcp/server.mjs"]
    }
  }
}

Optional env on the server process:

• CURSOR_BROWSER_WORKSPACE

• CURSOR_BROWSER_CLI_PORT

Or pass workspace on each tool call.

Tools

All tools accept optional workspace (project folder name or path) unless noted.

Screenshot note: When the page returns a data URL, the MCP layer can attach an image content block for vision-capable models, plus a text payload with the saved path.

Skills

npm install -g / cursor-browser setup copies skill/SKILL.md to:

• ~/.grok/skills/cursor-browser/SKILL.md

• ~/.claude/skills/cursor-browser/SKILL.md (if that tree exists)

• ~/.agents/skills/cursor-browser/SKILL.md (if that tree exists)

The skill teaches agents:

• Always route the correct Cursor window (windows / --workspace)

• Preferred snapshot → ref click/fill → wait loop

• When to screenshot, inspect, console, network

• Failure modes (stale refs, wrong project, connection refused)

Architecture

┌─ Cursor window: your-project ──────────────────────────┐
│  Extension host HTTP  127.0.0.1:1737x                   │
│         │                                              │
│         │  cursor.browserView.*                        │
│         ▼                                              │
│  Browser Tab                                           │
│  · refs via data-cursor-ref after snapshot             │
│  · DOM click/type/fill (not raw CDP Input)             │
└────────────────────────────────────────────────────────┘
                    ▲
                    │  loopback only
     CLI  ·  MCP  ·  scripts
   (Grok / Claude Code / Codex / shell)

On-disk state (~/.cursor-browser-cli/):

Ports start at 17373 and try up to 32 candidates if the preferred port is taken (one port per Cursor window).

How agents should use it

Typical product/UI session

1. browser_windows or cursor-browser windows

2. open / browser_open on http://localhost:… or staging URL

3. Read refs from the snapshot

4. click / fill / press

5. wait for URL or text

6. New snapshot after major UI change

7. screenshot or inspect when stuck

Multi-project day

Always pin the project:

cursor-browser --workspace project-a open http://localhost:3000
cursor-browser --workspace project-b open http://localhost:4000

Or set CURSOR_BROWSER_WORKSPACE in that agent’s shell profile / MCP env.

Switching agents mid-project

The Browser Tab is owned by the Cursor window, not by a single agent process. You can:

1. Use Cursor Agent for some steps (built-in tools)

2. Switch to Claude Code / Grok / Codex in the terminal

3. Continue with cursor-browser or MCP on the same tab

That continuity is the whole point of this tool.

Security

• The HTTP server binds to loopback only (127.0.0.1).

• Anyone who can reach that port on your machine can drive the Browser Tab (navigate, click, run page JS, read console/network).

• Treat it like a local debugger: do not tunnel or expose the port; do not run on untrusted multi-user machines without isolation.

• eval / browser_evaluate execute arbitrary page JavaScript — only run code you trust.

Troubleshooting

Logs: ~/.cursor-browser-cli/bridge.log

Repo layout

cursor-browser-cli/
├── README.md
├── LICENSE                 # MIT
├── package.json            # npm package (bins + postinstall setup)
├── cli/
│   └── cursor-browser      # CLI entry (Node)
├── extension/
│   ├── package.json
│   ├── extension.js        # HTTP API + cursor.browserView.*
│   └── snapshot.js         # Accessibility snapshot + refs
├── mcp/
│   └── server.mjs          # MCP stdio server → bin: cursor-browser-mcp
├── scripts/
│   ├── setup.js            # extension + skills install
│   └── install.sh          # thin wrapper → setup.js
└── skill/
    └── SKILL.md            # Agent skill template

No runtime npm dependencies — Node built-ins only (http, fs, path, os, etc.).

Development notes

• Extension activation: onStartupFinished

• Preferred port configurable via cursorBrowserCli.port

• Clients still understand legacy state dirs / names from earlier renames for smoother upgrades

• After changing extension code: cursor-browser setup (or npm run setup) and Reload Window

• Publish: npm publish (requires npm login)

License

MIT © Brandon Charleson

Contributing / sharing

This repo is intended to be shared as open source so CLI agents in Cursor can share one Browser Tab.

If you publish or fork:

1. Keep the why clear: multi-agent access to Cursor’s Browser Tab

2. Document both CLI and MCP equally

3. Stress workspace routing and the snapshot → ref → wait loop

Issues and PRs that improve multi-window routing, snapshot quality, or agent docs are especially welcome.