Integrates with Firefox through an extension that lets agents control existing Firefox tabs: read pages, click, type, fill forms, take screenshots, inspect network requests, run JavaScript, and interact with dialogs and frames.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@choro-mcp Check my open Gmail tab and summarize the latest unread email."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let coding agents use your real browser. Choro gives Claude Code (or any MCP client) the tabs you already have open in Chrome or Firefox, with your logins: read pages, click, type, fill forms, take screenshots, follow network traffic and read source code, on the sites you actually use.
agent ──MCP (stdio)──▶ choro-mcp ──WebSocket on 127.0.0.1, paired──▶ Choro extension ──▶ your tabsUnlike headless automation, Choro works in the browser you are looking at. It is built for the pages that make
automation hard: shadow DOM, iframes (cross-origin too), rich text editors, script-driven buttons, popups and
alert dialogs, single-page apps, password managers.
You need Node.js 20 or newer, and Chrome (or another Chromium browser) 116+ or Firefox 128+.
Install the extension.
Chrome: download choro-chrome-<version>.zip from the releases and unzip it (or build it,
see Development). Open chrome://extensions, turn on Developer mode, click Load unpacked
and pick the unzipped folder.
Firefox: install it from Firefox Add-ons or the
choro-firefox-<version>.xpi (signed by Mozilla) from the releases. For development, build it
and load dist/firefox/manifest.json from about:debugging → This Firefox → Load Temporary Add-on.
Add the server to your agent. For Claude Code:
claude mcp add choro -- npx -y choro-mcp@latestOther MCP clients: run npx -y choro-mcp@latest as a stdio server, e.g.
{"mcpServers": {"choro": {"command": "npx", "args": ["-y", "choro-mcp@latest"]}}}. On Windows, use
cmd /c npx -y choro-mcp@latest as the command.
Pair them. Run npx -y choro-mcp@latest pair, click the Choro icon in the browser's toolbar, paste the key into
Pairing key and click Pair. This is needed once per browser.
The extension's icon shows a green ON while an agent is connected (and a red ! if it isn't paired). Its
popup can pause agent control or change the port. The default is 8765; to use another, set it in the popup and give
the server the same one: claude mcp add -e CHORO_PORT=9000 choro -- npx -y choro-mcp@latest.
Related MCP server: browser-control
Tool | What it does |
| Work with your tabs. Without |
| Navigate and wait until the page is usable. |
| A text outline of the page with a ref like |
| The page's text and live HTML; its source as the server sent it, or any script or stylesheet. |
| The visible area, the whole page (scrolled and stitched) or one element. |
| Input on an element given by |
| Forms: text, date/time/color/range/number inputs, selects (also multiple), checkboxes, radios and switches, with validation errors reported. |
| Attach local files to a file input (also a hidden one behind an "Upload" button) or drop them on a drag-and-drop zone; no file dialog opens. Up to 32 MB per call. |
| Scroll the page, an element into view, or inside a container (feeds, virtual lists); wait for text or an element. |
| Answer an |
| The tab's requests with status and timing, one request's headers and bodies, or waiting for one (e.g. the POST a Save button sends). |
| Every frame on the page; run JavaScript in the page. |
Every action reports what it caused: a new page or URL, new tabs, downloads, dialogs, blocked popups and the network requests it triggered (with failures). Actions a person couldn't take are refused with the reason: clicking a disabled button or one behind a modal, typing into a read-only field.
Simulated and trusted input. By default input is simulated with the full sequence of DOM events, which works
with React, Vue, rich text editors and the like and shows no UI. A few sites ignore simulated events; for them pass
trusted: true (Chrome only) and Choro sends real input through Chrome's debugger. Chrome shows a "being
debugged" bar while that runs.
Dialogs. Pass dialog: "accept" or "dismiss" (and promptText) to the action that opens an
alert/confirm/prompt, and Choro answers it in the page. Otherwise the next call reports the dialog and its
text, and handle_dialog answers it (in Chrome; in Firefox only the user can).
Several agents at once. Any number of agent sessions can share the browser. The first choro-mcp to start
owns the port and the others connect through it; when it exits, another one takes over. Each session has its own
current tab and can't touch tabs another session is working in. list_tabs shows which are whose.
Several browsers at once. Chrome and Firefox (or several browser profiles, up to four) can be connected at the
same time, each with Choro installed and paired with the same key. list_tabs then shows every browser's tabs,
each marked with its browser. A call with a tabId goes to the browser that has that tab. Other calls go to the
browser the session last worked in. open_tab and select_tab take browser to choose one.
Everything works in both, except what needs Chrome's debugger API, which Firefox doesn't have: trusted input,
handle_dialog (use the dialog option instead), screenshots of elements larger than the window (Firefox gets the
visible part), and evaluate on pages whose Content Security Policy forbids eval. The Firefox build uses Manifest
V2, because Firefox lets Manifest V3 extensions take screenshots only right after the user clicks their icon.
Choro gives whoever controls the agent the same access to your browser that you have, including sites you're logged into. Treat it like that.
Pairing. The server and the extension only talk after both prove they know the pairing key (an HMAC
challenge-response in both directions, bound to both nonces and the port; the key never crosses the connection).
The key is kept in ~/.config/choro/pairing-key ($XDG_CONFIG_HOME/choro if set; on Windows %APPDATA%\choro),
readable only by you. Without it, nothing else — another program on your computer, another user, another
extension — can command the extension or impersonate the server. choro-mcp pair --new makes a new key: running
servers switch to it by themselves, and browsers need it pasted in again.
Local only. The server listens on 127.0.0.1. Web pages can't connect to it: browsers mark their connections with the page's origin, which the server refuses.
Nothing leaves your machine. Choro sends nothing anywhere except between the extension and the local server.
Only where an agent works. The page hooks Choro uses (to see dialogs, popups and network bodies) are switched
on only in tabs an agent works in, and network traffic is recorded only for those tabs, in memory. Cookies,
tokens and password-like fields (also in URLs, form uploads and WebSocket messages) are hidden from agents unless
they ask with showSecrets. A page an agent is working in can tell that Choro is there (its hooks are visible to
the page's scripts); other pages see the hooks' inactive wrappers at most.
Switch it off with Allow agent control in the popup.
Found a security problem? Please report it privately; see SECURITY.md.
Browsers don't let extensions into their own pages (chrome://, about:), the extension stores, or other
extensions. file:// pages need Allow access to file URLs (Chrome).
Chrome won't attach its debugger to a tab that contains a frame from another extension. Password managers such
as LastPass add one to pages with login forms. There, trusted input and handle_dialog don't work; simulated
input and the dialog option do. list_frames shows such frames.
Cross-origin frames are reached through refs from a snapshot; selector and name search the page, its
same-origin frames and shadow roots.
"Leave site?" dialogs can only be answered by you. Chrome cancels a dialog when you switch to another tab.
Screenshots need the browser window not to be minimized.
Simulated clicks don't count as user gestures, so browsers may block the popups they open. Choro says so; a
trusted click (Chrome) gets through.
extension/ the browser extension (one source for Chrome and Firefox)
background.js entry point; bg/ holds its modules (connection, sessions, commands, dialogs, network...)
page.js runs in pages: snapshots, refs, simulated input
page-hooks.js page-world hooks for dialogs, popups and network bodies (only while connected)
server/ the MCP server, published to npm as choro-mcp
tools/build.mjs builds dist/chrome and dist/firefox (--zip for release archives)
test/ hard test pages, their web server, and the end-to-end testcd server && npm install && npm test # the server: pairing, sharing, hand-off (no browser needed)
node tools/build.mjs # dist/chrome and dist/firefox
node test/e2e.mjs # end to end in separate Chromium and Firefox instancesThe end-to-end test builds the extension with a throwaway key, starts servers on a spare port and drives
test/torture.html, torture2.html and network.html in fresh, headless Chromium and Firefox profiles (your own
browser is never touched), including two agent sessions working at once. It needs python3 and chromium and
firefox on the PATH (or CHROMIUM / FIREFOX set to the binaries); a missing browser is skipped, except in CI.
--headed shows the browsers. The test pages can also be opened by hand: python3 test/serve.py, then
http://127.0.0.1:8701/torture.html.
MIT © Ivo Georgief
This server cannot be deployed
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Run multi-step tasks in a real Chrome browser: persistent environments, live view, human takeover.
