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

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

Related MCP server: browser-mcp

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

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