Skip to content
Back to search

browsercontrol

MarketplaceWorks with Claude CodeGitHub

MCP server that gives AI agents a real browser: annotated screenshots with numbered elements, so the agent clicks by number (Playwright, Set of Marks)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adityasasidhar--browsercontrol/badge.svg)](/listings/adityasasidhar--browsercontrol)

HTML

<a href="/listings/adityasasidhar--browsercontrol"><img src="/api/listings/adityasasidhar--browsercontrol/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need [uv](https://docs.astral.sh/uv/getting-started/installation/). 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.

**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](https://adityasasidhar.github.io/browsercontrol/guide/clients).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "name": "browsercontrol",
  3. "owner": {
  4. "name": "Aditya Sasidhar",
  5. "url": "https://github.com/adityasasidhar"
  6. },
  7. "metadata": {
  8. "description": "BrowserControl: vision-first browser automation for Claude Code."
  9. },
  10. "plugins": [
  11. {
  12. "name": "browsercontrol",
  13. "source": "./",
  14. "description": "Vision-first browser automation: every action returns a screenshot with numbered boxes over interactive elements, so Claude clicks by number instead of by selector. Bundles the BrowserControl MCP server and its usage skill.",
  15. "version": "0.3.1",
  16. "category": "development",
  17. "homepage": "https://adityasasidhar.github.io/browsercontrol/",
  18. "license": "MIT"
  19. }
  20. ]
  21. }
README.md · README · 179 lines
  1. <p align="center">
  2. <img alt="BrowserControl" src="https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/assets/logo-main.png" width="120"/>
  3. </p>
  4. <!-- mcp-name: io.github.adityasasidhar/browsercontrol -->
  5. <h1 align="center">BrowserControl</h1>
  6. <p align="center">
  7. <b>A real browser for your AI agent. It sees the page and clicks by number.</b>
  8. </p>
  9. <p align="center">
  10. <a href="https://pypi.org/project/browsercontrol/"><img src="https://img.shields.io/pypi/v/browsercontrol" alt="PyPI"></a>
  11. <a href="https://pypi.org/project/browsercontrol/"><img src="https://img.shields.io/pypi/pyversions/browsercontrol" alt="Python"></a>
  12. <a href="https://pepy.tech/projects/browsercontrol"><img src="https://static.pepy.tech/badge/browsercontrol" alt="Total downloads"></a>
  13. <a href="https://github.com/adityasasidhar/browsercontrol/blob/main/LICENSE"><img src="https://img.shields.io/github/license/adityasasidhar/browsercontrol" alt="MIT license"></a>
  14. </p>
  15. <p align="center">
  16. <a href="https://adityasasidhar.github.io/browsercontrol/"><b>Documentation</b></a> ·
  17. <a href="https://adityasasidhar.github.io/browsercontrol/guide/quickstart">Quickstart</a> ·
  18. <a href="https://adityasasidhar.github.io/browsercontrol/reference/">All 69 tools</a> ·
  19. <a href="https://adityasasidhar.github.io/browsercontrol/recipes/">Recipes</a> ·
  20. <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.adityasasidhar/browsercontrol">MCP Registry</a> ·
  21. <a href="https://github.com/adityasasidhar/browsercontrol/blob/main/README.es-ES.md">Español</a>
  22. </p>
  23. ---
  24. BrowserControl is an [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor, VS Code, or any other MCP client use a real Chromium browser on your machine.
  25. 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.
  26. <p align="center">
  27. <picture>
  28. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/assets/demo-dark.gif">
  29. <img alt="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" src="https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/assets/demo-light.gif" width="720">
  30. </picture>
  31. </p>
  32. ## Install
  33. You need [uv](https://docs.astral.sh/uv/getting-started/installation/). Everything else, including the browser, is set up on first run.
  34. **Codex** (installs the local MCP server and the BrowserControl skill):
  35. ```bash
  36. codex plugin marketplace add adityasasidhar/browsercontrol
  37. codex plugin add browsercontrol@browsercontrol
  38. ```
  39. **Claude Code** (installs the server and a skill that teaches Claude to use it):
  40. ```text
  41. /plugin marketplace add adityasasidhar/browsercontrol
  42. /plugin install browsercontrol@browsercontrol
  43. ```
  44. **OpenCode 2** (installs the local MCP server and the BrowserControl skill):
  45. ```bash
  46. opencode plugin add github:adityasasidhar/browsercontrol
  47. ```
  48. **VS Code or Cursor:** one click.
  49. <a href="https://insiders.vscode.dev/redirect/mcp/install?name=browsercontrol&amp;config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22browsercontrol%22%5D%7D"><img src="https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code"></a>
  50. <a href="https://cursor.com/en/install-mcp?name=browsercontrol&amp;config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJicm93c2VyY29udHJvbCJdfQ%3D%3D"><img src="https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white" alt="Install in Cursor"></a>
  51. **Anything else:** add this to your client's MCP config.
  52. ```json
  53. {
  54. "mcpServers": {
  55. "browsercontrol": {
  56. "command": "uvx",
  57. "args": ["browsercontrol"]
  58. }
  59. }
  60. }
  61. ```
  62. Restart your client and you're done. Setup for Claude Desktop, Gemini CLI, Zed, OpenCode, and others is in the [client guide](https://adityasasidhar.github.io/browsercontrol/guide/clients).
  63. ## Try it
  64. Ask your agent something that needs a browser:
  65. > Open Hacker News and tell me the top three stories.
  66. > Go to my app on localhost:3000, sign up with a test account, and tell me if anything breaks.
  67. > Find the cheapest flight from Berlin to Lisbon next Friday and show me the options.
  68. ## How it works
  69. 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:
  70. ```text
  71. Clicked element 5
  72. Found 23 interactive elements:
  73. [1] a - Home
  74. [2] input[search] - Search products
  75. [3] button - Search
  76. [4] a - Sign in
  77. ...
  78. ```
  79. 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.
  80. This is called [Set of Marks](https://adityasasidhar.github.io/browsercontrol/concepts/set-of-marks). It works on any site, including ones with messy markup, iframes, and shadow DOM.
  81. ## What your agent can do
  82. | | |
  83. | --- | --- |
  84. | **Browse** | Open pages, click, type, scroll, hover, drag, and press keys. `find("Checkout")` searches the whole page, not just what's visible. |
  85. | **Batch** | `act([...])` runs several steps in one call and returns one screenshot, which saves time and tokens. |
  86. | **Fill forms** | Pick from dropdowns, tick checkboxes, and upload files. |
  87. | **Read and extract** | Get a page as Markdown, pull out tables and links, or extract fields into JSON. |
  88. | **Use tabs and sessions** | Work across several tabs, or open isolated sessions side by side, each with its own cookies. |
  89. | **Debug** | Read console logs, page errors, and network requests with their headers and bodies. Export a HAR file. |
  90. | **Test edge cases** | Fake or block API responses, slow the network, go offline, and emulate phones, locations, timezones, and dark mode. |
  91. | **Record** | Save Playwright traces, and turn what the agent did into a runnable Playwright test. |
  92. See [all 69 tools](https://adityasasidhar.github.io/browsercontrol/reference/), with every parameter.
  93. ## Common setups
  94. **Run it hidden.** The browser opens a visible window by default. To run it headless (servers, CI), set `BROWSER_HEADLESS`:
  95. ```json
  96. "browsercontrol": {
  97. "command": "uvx",
  98. "args": ["browsercontrol"],
  99. "env": { "BROWSER_HEADLESS": "true" }
  100. }
  101. ```
  102. **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](https://adityasasidhar.github.io/browsercontrol/recipes/your-chrome).
  103. **Share one browser between clients.** Run it as an HTTP server, and point your clients at `http://127.0.0.1:8000/mcp`:
  104. ```bash
  105. uvx browsercontrol --transport http
  106. uvx browsercontrol --transport http --isolate-clients # a separate session for each client
  107. ```
  108. Every setting is listed in [Configuration](https://adityasasidhar.github.io/browsercontrol/reference/configuration).
  109. ## Good to know
  110. - **It runs locally.** The browser runs on your machine. Nothing goes through a BrowserControl server.
  111. - **Logins are kept.** The browser profile lives in `~/.browsercontrol/user_data`, so sites you sign in to stay signed in between runs.
  112. - **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](https://adityasasidhar.github.io/browsercontrol/concepts/comparison) to other approaches.
  113. - **The HTTP mode has no authentication.** Keep it on `127.0.0.1` unless you put something in front of it.
  114. - **Something not working?** Check [Troubleshooting](https://adityasasidhar.github.io/browsercontrol/help/troubleshooting), or [open an issue](https://github.com/adityasasidhar/browsercontrol/issues).
  115. ## For agents
  116. The docs are built to be read by agents too: [`llms.txt`](https://adityasasidhar.github.io/browsercontrol/llms.txt) indexes every page, [`llms-full.txt`](https://adityasasidhar.github.io/browsercontrol/llms-full.txt) has all of it in one file, and [`tools.json`](https://adityasasidhar.github.io/browsercontrol/tools.json) lists every tool with its parameters. Any docs page is also available as Markdown by adding `.md` to its address.
  117. ## Contributing
  118. Bug reports, fixes, and new tools are welcome.
  119. ```bash
  120. git clone https://github.com/adityasasidhar/browsercontrol && cd browsercontrol
  121. uv sync && uv run playwright install chromium
  122. uv run pytest
  123. ```
  124. The [contributing guide](https://adityasasidhar.github.io/browsercontrol/project/contributing) covers the checks, adding a tool, and working on the docs. Please also read [CONTRIBUTING.md](https://github.com/adityasasidhar/browsercontrol/blob/main/CONTRIBUTING.md).
  125. ## License
  126. [MIT](https://github.com/adityasasidhar/browsercontrol/blob/main/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.