pointclick

A browser MCP server in under 1,000 tokens. The page comes back as a numbered list of what you can click, type into or select. Your agent points at a number; pointclick clicks it.

url: https://en.wikipedia.org/wiki/Main_Page
title: Wikipedia, the free encyclopedia
[1] link 'Wikipedia The Free Encyclopedia' <CLICK>
[2] searchbox 'Search Wikipedia' <TYPE,CLICK>
[3] button 'Search' <CLICK>
...
(more below: 3156px; SCROLL_DOWN or observe(full=true))

text:
Welcome to
Wikipedia
...

act("TYPE", "2", "Ada Lovelace")   → the new list, once the page has settled
act("PRESS", "2", "Enter")

Why

Same task, same model (Claude Sonnet 5 in headless Claude Code), one browser MCP each — sign in, search, sort, open a record, read a number off it. 18 of 18 runs got it right.

Medians. Cost is the API price Claude Code reports; time is noisy at this sample size.

• Nine tools, under 1k tokens of definitions. Playwright MCP's are ~5k, Chrome DevTools MCP's ~7k, agent-browser's ~18k. Clients that load every tool up front pay that on every turn.
• Only what you can act on. No wrapper divs, no layout tree: controls, their state, and the visible text.
• Every action returns the settled page. No follow-up snapshot call, and no waiting for the network to go quiet: long-polls and streams don't stall it.

Quick start

Needs Python 3.12+ and uv. Uses your installed Chrome, or Playwright's Chromium if there is none (uvx --from pointclick playwright install chromium).

Claude Code

claude mcp add pointclick -- uvx pointclick

Cursor, Claude Desktop, Windsurf, and other clients — add to the MCP config:

{
  "mcpServers": {
    "pointclick": { "command": "uvx", "args": ["pointclick"] }
  }
}

VS Code

code --add-mcp '{"name":"pointclick","command":"uvx","args":["pointclick"]}'

Codex

codex mcp add pointclick -- uvx pointclick

Your first prompt

Open news.ycombinator.com, go to the second page, and tell me the top story there.

Tools

target is a number from the list ("3", or "3:2" for the second option of a select), or any Playwright selector ("input[type=password]", "text=Send", "role=button[name='OK']"). Password and file inputs are never in the list; reach them by selector.

Store screenshots

The screen is 1280×800 at scale 1 until navigate is given a device: "WxH@scale", plus " mobile" for a phone (touch, and the page's <meta viewport> is honoured), plus " dark" or " light" for the colour scheme. "dark" alone switches the scheme and keeps the size.

navigate("http://localhost:8081/home", device="440x956@3 mobile")
screenshot(path="shots/iphone-6.9/home.png")   → /abs/shots/iphone-6.9/home.png 1320x2868 png

Scale can't change on a live browser context, so a new device opens a new one, and show relaunches the browser. Cookies, localStorage, IndexedDB and the current page's sessionStorage (where some apps keep their login) carry over; other tabs and history don't. Saving to a path writes PNG (JPEG for .jpg), creates missing folders and keeps the image out of the agent's context, so a batch of captures costs a line each. close() goes back to 1280×800.

Your own browser

POINTCLICK_CDP attaches over the Chrome DevTools Protocol to a browser you started, so the agent works with that profile's cookies and logins. pointclick opens its own tab and leaves your other tabs alone; close() closes that tab and disconnects, and the browser keeps running.

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 --user-data-dir="$HOME/.pointclick/chrome"
claude mcp add pointclick -e POINTCLICK_CDP=http://localhost:9222 -- uvx pointclick

Chrome 136 and later ignore --remote-debugging-port on the default profile, so give it a --user-data-dir of its own and log in there once. While attached, show does nothing (the window is already yours), device changes only the size and dark/light (scale and mobile need a browser pointclick launches), and POINTCLICK_STATE is never written: the profile already keeps the logins, and pointclick won't copy them to a file.

How it works

• The list comes from one script that reads every visible control and the visible text in a single pass — adapted from jev-ultrafast (Browser Use × TypeSafe). It runs in every frame, cross-origin ones included, and a control that only repeats its wrapper's label is listed once.
• Settling. After an action, pointclick returns once the page has been still for 150 ms and no request younger than 0.5 s is pending — at most 2 s. Older requests (long-polls, streams) don't hold it up. If the page is still busy after that, WAIT returns the moment it changes.
• Numbers point at real elements, not at a position. If a framework re-renders the element, pointclick follows it when its label is unique on the page and says so; a duplicate label (two "Start" buttons) is refused rather than guessed.
• A timeout on a page that changed anyway is reported that way, so the agent checks before retrying instead of clicking twice.
• Playwright underneath handles selectors, uploads, popups (they become the current page), screenshots and the console. Every session is a fresh, isolated browser context.

server.py is ~400 lines and snapshot.js ~110. Small enough to read before you trust it.

Benchmarks

bench/ has a small SPA shaped like a real dashboard — demo login, a list with search and sort, a detail page, API calls over the network, and an optional long-poll like a realtime fallback.

With a real agent — headless Claude Code, built-in tools off, the task given in plain words:

uv run python bench/agent_race.py --runs 3 --model sonnet

Medians of 3 runs per column. Turns and tokens barely move between runs; time moves by up to a third with model latency, so read it as a range. Playwright MCP's action replies link to a snapshot file instead of including the page, so the model asks for a snapshot after each step. agent-browser's actions return nothing, so every step is an action plus a snapshot too.

Tools alone — the same flow driven by a script, so no model time is included:

uv run python bench/race.py --runs 8 --poll 0

agent-browser's tool time is lowest because its actions return nothing: it re-snapshots, and the script polls for free. In a real agent every one of those calls is a model turn.

Tool definitions, sent with every request by clients that don't load tools lazily (all four estimated the same way, JSON characters ÷ 3.5):

Measured on an M-series Mac with Chrome 153. Raw results are in bench/*.json.

When to use something else

• Playwright MCP — you need network interception, tracing, PDF export, or the full Playwright surface.
• Chrome DevTools MCP — performance traces, Lighthouse-style audits, deep DevTools debugging.
• agent-browser — you'd rather drive the browser from a shell (CLI + skills), want saved auth profiles, or need its long tail of commands.
• Stagehand — you want natural-language act/extract backed by its own model, or hosted browsers on Browserbase.

pointclick does one job: get an agent through a web app with as little text and as few turns as it can — locally, with no account and no second model.

Security

• Everything on a page — text, labels, titles — is untrusted input to your model. A page can try to instruct your agent. Keep the agent's permissions narrow and confirm consequential steps.
• Each session is an isolated browser context: no access to your Chrome profile, cookies or passwords. Nothing persists after close().
• POINTCLICK_CDP is the exception: the agent acts as you, signed in to everything that profile is, and so does anything else that can reach the debugging port. Keep the port on localhost and use a profile with only the logins the agent needs.
• evaluate runs arbitrary JavaScript in the page; upload reads files you name from disk, and screenshot(path=...) writes one.

Limits

• The list is viewport-only by default; long pages take SCROLL_DOWN or observe(full=true).
• Every action returns the whole list, not a diff.
• Chromium only, one page at a time per server. Calls sent in parallel run one after another.
• No network inspection, PDF export or dialog control; evaluate covers some of it.

Development

uv sync --group dev
uv run pytest     # 69 tests; fixture pages served from two local origins
uv run ruff check . && uv run ruff format --check .

To release, bump version in pyproject.toml, then push a matching tag (v0.1.0). release.yml publishes to PyPI through trusted publishing; there is no token to keep.

Credits

The page snapshot is adapted from jev-ultrafast, MIT © 2026 Browser Use — see LICENSE-jev.

License

MIT