Humanized Browser

Operate your real Chrome browser in a humanized way from Cursor: natural mouse paths, typing cadence, and scroll pauses — so everyday tasks feel like a person, not a bot.

Architecture

User (Cursor Agent)
    → MCP stdio (packages/mcp-server)
    → WebSocket 127.0.0.1:19501
    → Chrome extension (packages/extension)
    → Humanized click / type / scroll / navigate

Layer	Role
Cursor Agent	Plans the task and calls tools
MCP server	Tool surface, pairing token, localhost WS hub
Chrome extension	Snapshot + humanized execution on your tabs

We do not rebuild a daily LLM agent loop — Cursor is the brain. This repo is the hand.

Prerequisites

• Node.js 20+
• pnpm 9+ (npm install -g pnpm)
• Google Chrome (or Chromium)
• Cursor with Agent / MCP enabled

Setup

1. Install & build

pnpm install
pnpm build

2. Load the extension

1. Open chrome://extensions
2. Enable Developer mode
3. Load unpacked → select packages/extension/dist
4. Keep the extension enabled

3. Pair with the MCP server

When Cursor starts the MCP server it writes:

• ~/.humanized-browser/credentials.json — { token, port }
• Token also printed on stderr of the MCP process

Open the Humanized Browser popup → paste token → set port (default 19501) → Connect.
Badge shows ON when connected.

4. Cursor MCP config

Project config is already at .cursor/mcp.json (absolute path to the built MCP entry). After pnpm build, reload MCP in Cursor (Settings → MCP), or restart Cursor.

If you move the repo, update the args path in .cursor/mcp.json accordingly.

Tools

Tool	Purpose
browser_status	Extension online?
tabs_list	List tabs
navigate	Open URL (humanized pause after load)
snapshot	Compressed page tree + refs
click	Bezier mouse path + jitter
type	Variable key delays
scroll	Humanized scroll / scroll-into-view
wait	Delay or wait for selector/ref
screenshot	Viewport capture (prefer snapshot for actions)

Example prompt (in Cursor Agent)

Use humanized-browser tools: open https://example.com, snapshot the page, and click the “More information…” link if present.

Humanize defaults

Humanized timing is on by default. Popup Fast mode skips delays for debugging only — do not use it for real sites you care about.

Security

• WebSocket hub binds to 127.0.0.1 only
• Extension must present the pairing token
• No remote browser control in this MVP

Packages

• packages/shared — protocol + humanize helpers
• packages/mcp-server — MCP stdio + WS hub
• packages/extension — MV3 execution plane

End-to-end checklist

1. pnpm build succeeds
2. Extension loads from packages/extension/dist without errors
3. Cursor MCP shows humanized-browser connected
4. Popup Connect → status connected / badge ON
5. In Agent: call browser_status → connected
6. navigate → snapshot → click/type with visible humanized motion

Out of scope (later)

• Cursor SDK headless runner
• Native Messaging instead of WS
• Domain allowlists / recording