Repository avatar
AI Tools
v0.3.1
active

browsercontrol

io.github.adityasasidhar/browsercontrol

A real browser for AI agents: screenshots with numbered elements, so the agent clicks by number.

Documentation

BrowserControl

BrowserControl

A real browser for your AI agent. It sees the page and clicks by number.

PyPI Python Total downloads MIT license

Documentation · Quickstart · All 69 tools · Recipes · MCP Registry · Español


BrowserControl is an MCP server that lets Claude, Cursor, VS Code, or any other MCP client use a real Chromium browser on your machine.

After every action, the agent gets back a screenshot with a numbered box on every button, link, and field, plus the same list as text. To press the button marked 5, it calls click(5). No CSS selectors, no guessing coordinates.

Animated demo: numbered boxes appear on a shop page, the agent types into box 5, clicks box 6, the numbers rebuild on the results page, and it clicks box 9 to add an item to the cart, while a transcript shows each tool call

Install

You need uv. Everything else, including the browser, is set up on first run.

Codex (installs the local MCP server and the BrowserControl skill):

codex plugin marketplace add adityasasidhar/browsercontrol
codex plugin add browsercontrol@browsercontrol

Claude Code (installs the server and a skill that teaches Claude to use it):

/plugin marketplace add adityasasidhar/browsercontrol
/plugin install browsercontrol@browsercontrol

OpenCode 2 (installs the local MCP server and the BrowserControl skill):

opencode plugin add github:adityasasidhar/browsercontrol

VS Code or Cursor: one click.

Install in VS Code Install in Cursor

Anything else: add this to your client's MCP config.

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

Restart your client and you're done. Setup for Claude Desktop, Gemini CLI, Zed, OpenCode, and others is in the client guide.

Try it

Ask your agent something that needs a browser:

Open Hacker News and tell me the top three stories.

Go to my app on localhost:3000, sign up with a test account, and tell me if anything breaks.

Find the cheapest flight from Berlin to Lisbon next Friday and show me the options.

How it works

Each time the agent does something, BrowserControl waits for the page to settle, takes a screenshot, numbers everything you can interact with, and sends back both:

Clicked element 5

Found 23 interactive elements:
  [1] a - Home
  [2] input[search] - Search products
  [3] button - Search
  [4] a - Sign in
  ...

The agent reads the picture to understand the page, then picks a number for its next action. Numbers are rebuilt after every step, so they always match what's on screen right now. If something has moved or gone, the tool says so instead of clicking the wrong thing.

This is called Set of Marks. It works on any site, including ones with messy markup, iframes, and shadow DOM.

What your agent can do

BrowseOpen pages, click, type, scroll, hover, drag, and press keys. find("Checkout") searches the whole page, not just what's visible.
Batchact([...]) runs several steps in one call and returns one screenshot, which saves time and tokens.
Fill formsPick from dropdowns, tick checkboxes, and upload files.
Read and extractGet a page as Markdown, pull out tables and links, or extract fields into JSON.
Use tabs and sessionsWork across several tabs, or open isolated sessions side by side, each with its own cookies.
DebugRead console logs, page errors, and network requests with their headers and bodies. Export a HAR file.
Test edge casesFake or block API responses, slow the network, go offline, and emulate phones, locations, timezones, and dark mode.
RecordSave Playwright traces, and turn what the agent did into a runnable Playwright test.

See all 69 tools, with every parameter.

Common setups

Run it hidden. The browser opens a visible window by default. To run it headless (servers, CI), set BROWSER_HEADLESS:

"browsercontrol": {
  "command": "uvx",
  "args": ["browsercontrol"],
  "env": { "BROWSER_HEADLESS": "true" }
}

Use your own Chrome. Start Chrome with --remote-debugging-port=9222, then ask the agent to connect to it. It opens its own tab and leaves yours alone. How to set it up.

Share one browser between clients. Run it as an HTTP server, and point your clients at http://127.0.0.1:8000/mcp:

uvx browsercontrol --transport http
uvx browsercontrol --transport http --isolate-clients   # a separate session for each client

Every setting is listed in Configuration.

Good to know

  • It runs locally. The browser runs on your machine. Nothing goes through a BrowserControl server.
  • Logins are kept. The browser profile lives in ~/.browsercontrol/user_data, so sites you sign in to stay signed in between runs.
  • It's built for vision models. Every action returns an image. That gives the agent the full picture, but uses more tokens than text-only tools. See how it compares to other approaches.
  • The HTTP mode has no authentication. Keep it on 127.0.0.1 unless you put something in front of it.
  • Something not working? Check Troubleshooting, or open an issue.

For agents

The docs are built to be read by agents too: llms.txt indexes every page, llms-full.txt has all of it in one file, and tools.json lists every tool with its parameters. Any docs page is also available as Markdown by adding .md to its address.

Contributing

Bug reports, fixes, and new tools are welcome.

git clone https://github.com/adityasasidhar/browsercontrol && cd browsercontrol
uv sync && uv run playwright install chromium
uv run pytest

The contributing guide covers the checks, adding a tool, and working on the docs. Please also read CONTRIBUTING.md.

License

MIT

PYPI
browsercontrol
Install Command
pip install browsercontrol
Runtime: uvx