tether
Provides browser automation for shared Brave tabs via the Tether extension, letting agents read and interact with pages, fill and submit forms, inspect network and console data, save media/downloads, and change site appearance or behavior.
Provides browser automation for shared Firefox tabs through the Tether extension and native messaging bridge, enabling page reading, form interaction, network/console inspection, media/download saving, and site customization.
Provides browser automation for shared LibreWolf tabs through the Tether extension and Firefox bridge, allowing agents to read pages, fill forms, click through flows, inspect network/console data, save media/downloads, and adjust site behavior.
Tether lets Claude Code, Codex or any other MCP client use the browser you already use, signed in as you. You choose which tabs it gets. From there the agent can read pages, fill and submit forms, click through flows, read the network log and console, save files and media, and change how a site looks or behaves.
A browser extension (Chrome, Brave, Edge and other Chromium browsers; Firefox, Zen and other Firefox forks) talks to a small local host, and every MCP agent on the machine connects to that host. Nothing on a tab is visible to an agent until you share it or approve the agent's request.
Ideas, feedback and early builds live in the #tether channel of the KuroLabs Discord. The most requested ideas get built first.
Contents
Related MCP server: Chromeflow
Quick start
You need Node 20 or newer.
npm install -g tether-browser
tether setupsetup prints the lines that add Tether to your agents, prints your pairing key, and registers the bridge Firefox-based browsers use. Then:
Add Tether to your agent with the line
setupprints. It uses full paths, which works everywhere, including Windows. For Claude Code it looks like:claude mcp add --scope user tether -- node /path/to/node_modules/tether-browser/host/cli.jsCodex, in
~/.codex/config.toml(single quotes, so Windows backslashes stay literal):[mcp_servers.tether] command = 'node' args = ['/path/to/node_modules/tether-browser/host/cli.js']Any other MCP client runs the same command as a stdio server.
Install the extension from the latest release.
Firefox, Zen, LibreWolf, Floorp or Waterfox: download
tether-firefox-<version>.xpiand open it with your browser, or useabout:addons, the gear menu, Install Add-on From File. It's signed by Mozilla, and no key is needed; the bridge supplies it.Chrome, Brave or Edge: download
tether-chrome-<version>.zipand unzip it, openchrome://extensions, turn on Developer mode, click Load unpacked and pick the unzipped folder. Click the Tether icon and paste the pairing key.Install the skill so agents know when and how to use Tether (see The skill).
Check everything with
tether doctor.
Open a page, click the Tether icon and choose Share this tab, or just ask your agent to do something in the browser and approve its request.
From source
git clone https://github.com/udaysinh-git/tether.git
cd tether
npm install
npm run build
node host/cli.js setupThen load dist/chrome as an unpacked extension, or in Firefox open about:debugging, This Firefox, Load Temporary Add-on and pick dist/firefox/manifest.json.
How it works
Claude Code ─┐ ┌─ Chrome extension ──── shared tabs
Codex ───────┼─ tether (stdio) ─ HTTP ─ host ┤
other MCP ───┘ 127.0.0.1:47821 └─ Firefox bridge ─ Firefox extension ── shared tabsEach agent starts tether as an ordinary stdio MCP server. The first one starts the host in the background and later ones join it, so every agent sees the same browsers. Chromium extensions connect to the host over a local WebSocket. Firefox upgrades an extension's ws://127.0.0.1 connection to wss://, which can't reach a local server, so Firefox-based browsers start a small native messaging bridge instead; the bridge also starts the host when needed and fills in the pairing key. The host quits after 30 minutes with nothing connected.
A tab becomes available to agents in one of these ways:
You click Share this tab in the popup.
An agent calls
start_sessionand you approve it.A shared page opens a new tab or window (a link with
target="_blank",window.open). Tabs you open yourself don't count.The agent opens a tab with
open_tab, or any tab is opened inside the agent's own window.You turn on bypass mode, which makes every tab available until you turn it off or close the browser.
A shared tab gets a gold badge on the toolbar icon and a small status panel on the page with the agent's name, its latest action, Pause and Stop.

Using it
Sessions an agent starts
An agent doesn't need you to click first. It calls start_session with a one-sentence reason, and a prompt in your browser asks you:
Its own window (the default): a new window in your browser, signed in as you. The agent works only in that window's tabs, so your own tabs stay private and keep working.
end_sessioncloses it, or you close it.The tab you're on (
mode: "current"): for "help me with this page".

Watching and stepping in
The agent has a visible cursor: a gold pointer with its name moves to each element before it clicks, types or picks something, and clicks show a small ripple.

Pause on the status panel or in the popup holds the agent. It can still read the page, but every click, keystroke and navigation is refused until you press Resume. When the agent reaches something only you should do, like a CAPTCHA, a code from your phone, a login or a payment confirmation, it calls wait_for_user. The tab comes to the front with its message and a Done button, and it carries on when you press it.

Drag the status panel anywhere on the page; double-click it to put it back in the corner. To keep pages clear, turn off Show status on the page in the popup. It then appears only when the agent needs you.
Reading and acting
snapshot gives the agent the page as an outline: headings, text and every control, each with a ref like [e14]. It acts by ref with click, type, fill_form, select_option, press_key, hover, scroll and upload_file, and each action returns a fresh outline. Content inside cross-origin iframes (payment forms, embedded forms, widgets) is part of the outline, with refs like [f12.e5] that work in every tool.
In Chromium, Tether uses the browser's debugger, so clicks and keystrokes arrive as real input, scripts run on pages with strict security policies, and the network log includes response bodies. Chromium shows a "started debugging this browser" bar while that is active. Firefox has no debugger API, so there clicks and typing are DOM events, which nearly every site accepts.
Debugging a site
network_requests lists every request since the tab was shared, network_request shows one with headers and both bodies, console_messages returns console output and uncaught errors, and cookies lists the page's cookies, including httpOnly ones.
Media and downloads
list_media lists the images (including blob: ones), video, audio, canvases and background images on a page, plus HLS and DASH streams and media files from the network log. save_media saves any of them to ~/.tether/media/<site>/ with your cookies; blob: URLs and canvases are read out of the page, and streams are joined into one .mp4 with ffmpeg if it's installed. video_frame returns the frame a video is showing.
After a click that downloads something, wait_for_download returns the file's path, and download_file fetches a URL on a shared site with your cookies. Agents only see downloads that started while a tab was shared, never your download history.
Bypass mode
When a task needs tabs you already have open, the agent calls request_bypass with a reason and you allow or decline it in a prompt. You can also turn it on from the popup. While it's on, every tab is available and any tab the agent touches gets the badge and status panel. It turns off when you switch it off, press Stop everything or close the browser.
Look, motion and sound
The interface is dark on purpose: Charcoal #1A1A1A, Jet #2D2D2D, Davy's Gray #5A5A5A, Off White #FFFBF0 and one accent, Metallic Gold #D4AF37, which always means "an agent can use this". Surfaces are flat with hairline borders.
Buttons are pills that press in and spring back, switches stretch as they slide, the popup animates between states instead of redrawing, and the status panel on the page changes shape on one spring as it moves between Shared, Paused and "needs you". Messages arrive in a stack of toasts that fans out when you point at it.
Short synthesised sounds (no audio files) mark sharing, stopping, pausing, switches, prompts, an agent asking for you, and watcher alerts, plus a quiet tick as the agent clicks. Turn them off with Play sounds in settings.
The skill
skills/tether-browser/SKILL.md tells agents to use Tether for browser work instead of Playwright, and covers starting sessions, the outline-and-ref loop, iframes, debugging, media, watchers, restyling, scripts, reading recordings, and when to ask you first. Link it into each agent's skills folder so it stays up to date. With the npm install, the folder is at $(npm root -g)/tether-browser/skills/tether-browser; from a source checkout, run this in the repo:
foreach ($d in "$env:USERPROFILE\.claude\skills", "$env:USERPROFILE\.codex\skills", "$env:USERPROFILE\.agents\skills") {
New-Item -ItemType Junction -Path "$d\tether-browser" -Target "$PWD\skills\tether-browser"
}On macOS or Linux: ln -s "$PWD/skills/tether-browser" ~/.claude/skills/, and the same for the other folders.
Changing sites
Requests
Request a change in the popup takes a note plus pasted, dropped or attached images: a screenshot of a site you like, a mockup, a sketch. Pick lets you click any part of the page and write a note about it; the agent then also gets that element's selector, text, HTML and outline, a crop of it and a screenshot of the page. Sending either one shares the tab.
Tell your agent to check Tether. It reads the request with get_requests, previews CSS on the live tab with apply_css, checks it with screenshot, saves it with save_style, adds a script when CSS isn't enough, and replies with resolve_request. The reply shows under the request in the popup.
Styles and scripts
Styles apply on every visit to matching pages in every connected browser. Scripts are either manual, with a Run button in the popup, or automatic, running on every page load once user scripts are allowed (Chrome: Allow user scripts on the extension's Details page; Firefox: the button in Tether's settings). Every style and automatic script has its own switch in the popup and settings.
The settings page has a gallery of everything, grouped by site, with before and after screenshots for styles. Each item can be downloaded, published as a secret GitHub Gist through the gh CLI (the Gist's raw link installs it in Tampermonkey or Stylus), or deleted.
Compatible with Tampermonkey and Stylus
Each script is a standard userscript and each style is standard UserCSS:
~/.tether/scripts/fill-timesheet.user.js works in Tampermonkey and Violentmonkey
~/.tether/styles/dark-dashboard.user.css works in Stylus// ==UserScript==
// @name Fill timesheet
// @namespace tether
// @version 1.0.2
// @description Fills this week with 9:30 to 18:00
// @match https://erp.example.com/timesheet*
// @grant GM_registerMenuCommand
// @run-at document-idle
// @tether-run manual
// ==/UserScript==
(function () {
// Manual: a menu command in Tampermonkey and Violentmonkey, the Run button in Tether.
const run = function () {
// tether:body start
document.querySelectorAll("input.start").forEach((el) => (el.value = "09:30"));
document.querySelectorAll("input.end").forEach((el) => (el.value = "18:00"));
return "filled";
// tether:body end
};
return typeof GM_registerMenuCommand === "function" ? GM_registerMenuCommand("Fill timesheet", run) : run();
})();Every save bumps @version, so other managers notice updates. In the other direction, Install on the settings page (or the agent's install_userscript) takes .user.js and .user.css files from Greasy Fork, OpenUserJS, userstyles.world or anywhere else and keeps them unchanged. Tether supports @match, @include, @exclude, @exclude-match and @run-at; GM_addStyle, GM_getValue, GM_setValue, GM_deleteValue, GM_listValues, GM_xmlhttpRequest, GM_openInTab, GM_setClipboard, GM_notification, GM_registerMenuCommand, the GM.* promise versions and unsafeWindow; and UserCSS @-moz-document rules (url, url-prefix, domain, regexp).
Edit or delete the files directly and every connected browser picks up the change.
Recording and site knowledge
Record in the popup records the current visit; Always record on a site records every visit there. A coral dot on the page shows it's running. Tether records interactions and structure, not video:
each click, with the element's role, name, a CSS selector that finds it again, its position and the section it's in
what you type and choose, form submits, and Enter, Escape and shortcut keys
every page you open, single-page apps included, and each page's outline as it changes
the site's API calls: method, URL, status and timing
Passwords, card numbers, one-time codes and fields that look like them are always masked, and settings can stop recording typed text entirely. Recordings are saved per site under ~/.tether/sites/<host>/; the extension holds them until the host is running.
Agents read this back with site_map, which folds every session into one summary of the site's pages, the controls you actually use on each, the fields you fill, the APIs behind them and your usual paths. site_map with a page path gives that page's full outline, site_sessions replays a session step by step, and agents keep what they learn in site_notes, which appears at the top of the map next time.
Watchers
Ask for something like "tell me when this drops below 2,000" or "when the results are posted" and the agent saves a watcher. The browser loads the page on a schedule with your cookies, and a small check decides whether to tell you. Fetch mode reads the URL directly, which suits the JSON APIs agents find in the network log; tab mode opens the page in a background tab for pages built by JavaScript. Alerts arrive as browser notifications and, if you set a topic in settings, through ntfy on your phone. Watchers run while the host is running and a browser is connected, and each has a switch in the popup and settings.
Tools
Tool | What it does |
| The tabs the agent may use, with handles like |
| Ask for its own window or your current tab; close the window or give the tab back |
| The page as an outline with refs; plain visible text |
| Act on elements by ref |
| Keys and shortcuts, scrolling, waiting for text to appear or go |
| Attach files from disk to a file input, including hidden ones |
| Move around and manage tabs |
| An image of the tab; JavaScript in the page's own context |
| Hand the tab to you with a message and continue when you press Done |
| Network log with bodies, console output, cookies |
| Media and streams on the page, saved to disk; the current video frame |
| Files the site produces, with their paths |
| Your change requests and picked elements; a reply in the popup |
| Preview CSS without saving |
| Site styles as UserCSS |
| Userscripts in Tampermonkey's format |
| Install a |
| Recordings and notes about how you use a site |
| Scheduled checks that notify you |
| Ask for access to every tab |
Settings
Tether's settings page (popup, then Settings) has:
Connection: pairing key and port (Chromium only; Firefox doesn't need them).
Agent sessions: let agents ask to start a session; ask before an agent opens its own window; show the agent's cursor; play sounds; show the status panel on pages.
Real input (Chromium): use the debugger for clicks, typing and network capture.
Recording: record what you type; sites recorded automatically.
Gallery: every style and script by site, with switches, Download, Publish and Delete.
Watchers: switches, Check now and Delete.
Notifications and publishing: ntfy topic and server, GitHub account for Gists.
Install: add a
.user.jsor.user.cssfile.
Keeping it installed in Firefox
Temporary add-ons disappear when the browser closes. To keep Tether:
Sign it as an unlisted add-on, which only you receive. Create API credentials at addons.mozilla.org (Tools, Manage API Keys), set
WEB_EXT_API_KEYandWEB_EXT_API_SECRET, bumpversioninpackage.jsonand runnpm run sign:firefox. Install the.xpifromdist/throughabout:addons, the gear menu, Install Add-on From File. Later versions install over it and keep your settings.Or, in browsers that allow unsigned add-ons (Firefox Developer Edition, Nightly and some forks), set
xpinstall.signatures.requiredtofalseinabout:config, runnpm run pack:firefoxand installdist/tether-firefox-<version>.xpithe same way.
Permissions, security and privacy
The extension asks for broad permissions so pages can't stop the agent from doing what you asked. They only apply to tabs you've shared or approved, or every tab while bypass mode is on.
Permission | Used for |
Access to all sites | Reading and acting on whatever you share |
| Real clicks and keys, scripts on strict-CSP pages, network bodies, console |
| Network log; in Firefox also fetch/XHR bodies and lifting CSP on shared tabs |
| The outline and actions; saved scripts |
| The cookies tool; download paths; watcher alerts |
| The bridge the browser starts |
| Tracking shared tabs and reconnecting after the browser suspends the extension |
Security:
The host listens on
127.0.0.1only and refuses HTTP requests with anOriginheader or an unexpectedHost, so web pages can't reach it, including through DNS rebinding.Agents and Chromium extensions need the pairing key from
~/.tether/config.json;tether key --newreplaces it. Firefox's bridge reads it locally.The host accepts WebSocket connections only from browser-extension origins, and the extension never takes commands from web pages.
Anyone who can run programs as your user can read the key and drive shared tabs. Treat sharing a tab like handing someone your mouse.
Agents are told to ask before paying, sending messages or deleting things. That is an instruction to the model, not something Tether enforces, so watch the status panel when it matters.
What sites can see: the status panel and cursor live in a closed shadow root, the outline code runs in the extension's isolated world, and nothing is added to the page's own JavaScript unless a script is run there. Tether doesn't spoof fingerprints or try to defeat bot detection; agent-paced browsing can still look automated, and some sites' terms forbid automation.
Command line
npm install -g tether-browser puts tether on your PATH. From a source checkout, use npm link or node host/cli.js.
tether # stdio MCP server (what agents run)
tether serve # host in the foreground with logs
tether status # connected browsers, agents and shared tabs
tether doctor # checks every piece of the setup and says what to fix
tether setup # agent config lines, pairing key, Firefox bridge registration
tether key # print the pairing key
tether key --new # replace it
tether install-native [--chrome-id <id>] # register the bridge againFiles Tether keeps
~/.tether/
config.json port, pairing key, ntfy topic, Gist account
host.log host log when an agent or the bridge started it
scripts/ userscripts (.user.js)
styles/ UserCSS (.user.css)
gallery/ before and after screenshots, Gist links
sites/<host>/ recordings, page outlines and notes per site
requests/ change requests and their images
watchers/ watcher definitions and last results
media/<site>/ files saved with save_media
native/ the Firefox bridge launcher and manifestDevelopment
host/ cli.js, shim.js (stdio bridge for agents), daemon.js (HTTP + WebSocket), hub.js,
tools.js, native.js and install-native.js (Firefox bridge), scripts.js (userscript and
UserCSS files), sites.js (recordings), requests.js, media.js, watchers.js, gallery.js,
doctor.js, config.js
extension/ background.js, content.js (outline, actions, cursor, status panel, recorder, picker),
motion.js (springs, in-place rendering), toast-stack.js, sounds.js, ui.css,
popup/, options/, prompt/, offscreen/ (plays alert sounds in Chromium), fonts/
scripts/ build-ext.js (dist/chrome, dist/firefox), make-icons.js
skills/ tether-browser, the agent skill
test/ e2e.mjs, features.mjs, shots.mjsnpm run build # after any change in extension/
npm test # both end-to-end suites, with and without the debugger
npm run shots # screenshots of the popup, page UI and settings into test/shots
npm run pack:firefox # unsigned .xpi
npm run sign:firefox # signed unlisted .xpi (needs the AMO API key)
npm run doctorThe tests load the built extension into Playwright's Chromium, serve test pages, connect an MCP client through the stdio shim and drive every tool: sharing, the outline, forms, real clicks, network and console capture, sessions, bypass, pausing, cross-origin iframes, media, downloads, picked elements, requests, styles and scripts, recording and the site map, watchers, gallery screenshots and sharing that survives an extension reload. --fallback repeats a suite without the debugger, which is the path Firefox takes. Firefox itself is checked with npx web-ext lint -s dist/firefox.
Known limits
Without the debugger (all of Firefox, or Chromium with Real input off),
run_js, a script's Run button and tab-mode watchers use the browser's user scripts API, so allow user scripts once: in Firefox with the button in Tether's settings, in Chromium with Allow user scripts on Tether's Details page. Firefox needs version 153 or newer.Canvas-drawn apps (Figma, Google Sheets' grid, games) have little in the outline to act on; use
screenshotandrun_js.Network and console logs start when a tab is shared and keep the last 400 entries per tab.
Screenshots without the debugger, including all Firefox screenshots, bring the tab to the front first.
Imported userscripts:
@requireand@resourcearen't loaded,GM_xmlhttpRequestuses the page'sfetchand so is subject to CORS, andGM_setValuevalues are stored per site.Imported UserCSS that uses
@varsettings or a preprocessor isn't supported.Tab-mode watchers load the URL directly, so pages that only work when reached by clicking through a single-page app can show an error page; point the watcher at a URL that loads on its own.
An agent only sees a change request when it calls
get_requests, so tell yours to check after you send one.
Contributing
Issues and pull requests are welcome.
Open an issue first for anything large, so we can agree on the approach.
Run
npm run buildandnpm testbefore sending a pull request.npm testruns both end-to-end suites with and without the debugger, which is the path Firefox takes.Keep the extension free of remote code and new permissions unless the change needs them, and say why in the pull request.
Talk to us in the Tether Discord, where the roadmap comes from.
Security problems: please report them privately through GitHub's "Report a vulnerability" on this repository rather than in a public issue.
Licence
MIT, (c) 2026 Udaysinh Sapate, Kuro Labs. The interface sounds come from Bencho (MIT) and the fonts are Inter and Plus Jakarta Sans (SIL Open Font License); see NOTICE.
Available Tools
53 toolsapply_cssA
Preview CSS on a shared tab without saving it. Each call replaces the previous preview on that tab; navigation clears it. Check the result with screenshot, then save_style.
Inputs: css (required), tab.
clear_previewC
Remove the CSS preview from a tab.
Inputs: tab.
clickC
Click an element.
Inputs: ref (required), tab, double.
close_tabC
Close a shared tab.
Inputs: tab.
console_messagesARead-only
Read console output and uncaught errors from a shared tab since it was shared.
Inputs: tab, clear, level, limit.
cookiesARead-only
List the cookies the browser would send to the tab's current page, including httpOnly ones.
Inputs: tab.
delete_scriptCDestructive
Delete a saved script.
Inputs: name (required).
delete_styleCDestructive
Delete a saved style.
Inputs: name (required).
delete_watcherCDestructive
Delete a watcher.
Inputs: name (required).
download_fileA
Download a URL through the user's browser, with their cookies, and get the saved file's path. Limited to sites of shared tabs unless bypass mode is on.
Inputs: url (required), tab, browser, filename.
end_sessionA
Finish a session you started: closes the window start_session opened for you (all of them if you don't name one). With tab, stops using that shared tab instead, leaving it open for the user.
Inputs: tab, windowId.
fill_formB
Fill several fields at once. Text fields take a string, checkboxes and radios take true or false, selects take the option label or value.
Inputs: fields (required), tab.
get_requestsARead-only
Read change requests the user sent from the Tether popup: what they want changed on a site, often with reference images (screenshots, mockups, mood boards). The tab they sent it from is shared with you. Handle open requests, then call resolve_request.
Inputs: id, status.
get_scriptBRead-only
Read a saved script, to change it. Returns the editable body for scripts you saved, or the whole file for imported ones.
Inputs: name (required).
get_styleBRead-only
Read a saved style, to change it. Returns the editable CSS for styles you saved, or the whole UserCSS file for imported ones.
Inputs: name (required).
hoverB
Move the pointer over an element, e.g. to open a menu.
Inputs: ref (required), tab.
install_userscriptA
Install a userscript (.user.js) or user style (.user.css) from a URL, such as Greasy Fork, OpenUserJS or userstyles.world, or from pasted text. It is saved unchanged. @require'd libraries and style preprocessors (Stylus, Less) are not supported.
Inputs: url, text.
list_downloadsBRead-only
List files downloaded while tabs were shared with you (not the user's whole download history).
Inputs: tab, browser.
list_mediaARead-only
List the media on a shared tab: images, video and audio (with size, length, playing state), canvases and CSS background images, plus HLS/DASH streams and media files the page loaded (from the network log). Each has an id like m3 for save_media. Streams only appear after the page has requested them, so start playback first.
Inputs: tab.
list_scriptsARead-only
List the user's userscripts: ones you saved and ones they imported. They live in ~/.tether/scripts as .user.js files, appear in the Tether popup on matching sites, and work unchanged in Tampermonkey or Violentmonkey.
Inputs: no named parameters.
list_stylesARead-only
List saved site styles, yours and imported ones.
Inputs: no named parameters.
list_tabsARead-only
List the browser tabs you can use. Normally these are the tabs the user shared by clicking Tether, plus tabs you or those pages opened. If the user has turned on bypass mode, every tab is listed.
Inputs: no named parameters.
list_watchersBRead-only
List watchers with their last result.
Inputs: no named parameters.
network_requestARead-only
Show one captured request in full: request and response headers, request body and response body.
Inputs: id (required), tab, maxChars.
network_requestsARead-only
List network requests made by a shared tab since it was shared (newest last): id, method, status, type, time, size, URL. Use network_request with an id to see headers and bodies.
Inputs: tab, type, clear, limit, +2 more.
open_tabB
Open a URL in a new tab in the user's browser. The new tab is shared with you.
Inputs: url (required), opener, browser.
press_keyB
Press a key, optionally on an element. Examples: "Enter", "Escape", "Tab", "ArrowDown", "Control+a".
Inputs: key (required), ref, tab.
read_textARead-only
Get the visible text of the page, or of one element, as plain text. Good for reading articles, tables and results.
Inputs: ref, tab, maxChars.
request_bypassA
Ask the user for bypass mode, which gives you every open tab in the browser instead of only the shared ones. The browser shows the user a prompt with your reason and waits up to two minutes for an answer. Only ask when the task needs other tabs.
Inputs: reason (required), browser.
resolve_requestA
Mark a change request done and leave a short reply the user sees in the popup (what you changed, and how to turn it off).
Inputs: id (required), reply (required).
run_jsA
Run JavaScript in the page's own context (page globals are visible) and return the result of the last expression, awaited if it is a promise. Works on sites with a strict CSP. Use for reading data the outline does not show or driving page APIs directly.
Inputs: code (required), tab.
run_scriptC
Run a saved script in a shared tab and return its result.
Inputs: name (required), tab.
run_watcherA
Run a watcher now and return what its check produced. Set notify to true to send the notification if it fires; by default this is a dry run that still records the value as the new baseline.
Inputs: name (required), notify.
save_mediaA
Save an item from list_media (or any URL) to disk under ~/.tether/media//, using the browser's cookies. Handles normal files, blob: and data: URLs, canvases, and HLS/DASH streams (through ffmpeg). Returns the file path.
Inputs: id, tab, url, filename, +1 more.
save_scriptA
Save a reusable userscript. code is the body of a function: plain JavaScript with full DOM access in the page, no imports; use return to hand a result back to run_script. These GM_ APIs work in Tether and in Tampermonkey: GM_addStyle, GM_getValue, GM_setValue, GM_deleteValue, GM_listValues, GM_xmlhttpRequest, GM_openInTab, GM_setClipboard, GM_notification, unsafeWindow. run=manual puts a Run button in the popup (and a menu command in Tampermonkey); run=auto runs on every matching page load. Saving an existing name replaces it and bumps its version.
Inputs: code (required), name (required), matches (required), run, +2 more.
save_styleA
Save CSS that restyles a site on every visit, in every connected browser. It is stored as a UserCSS file (~/.tether/styles/.user.css) that also installs unchanged in Stylus. It shows in the popup on matching pages, where the user can switch it off. Saving an existing name replaces it and bumps its version. Use !important where the site's own rules win. For changes CSS can't do, pair it with save_script (run=auto).
Inputs: css (required), name (required), matches (required), tab, +1 more.
save_watcherA
Watch a page and notify the user when something they care about happens ("tell me when the price drops below 2000", "when results are posted"). The browser fetches the page on a schedule with the user's cookies. mode=fetch (default) loads the URL without rendering it, so point it at the JSON API you found with network_requests when there is one; check is a function body that receives response = { status, url, text, json, contentType } and has no DOM. mode=tab opens the page in a background tab for a moment, for pages built by JavaScript; check runs in the page with full DOM access. check either returns a value (the user is notified when it changes from the last run) or { notify: true/false, message, value }. Notifications go to a browser notification and, with notify including "ntfy", to the user's ntfy topic. Test with run_watcher.
Inputs: url (required), name (required), check (required), mode, +3 more.
screenshotARead-only
Take a screenshot of the visible part of a shared tab. The tab is brought to the front first.
Inputs: tab.
scrollB
Scroll an element into view, or scroll the page by a number of pixels.
Inputs: dy, ref, tab.
select_optionB
Choose one or more options in a select element, by label or value.
Inputs: ref (required), values (required), tab.
site_listARead-only
List sites Tether has recorded the user using (clicks, typing, pages, API calls), and sites with saved notes.
Inputs: no named parameters.
site_mapARead-only
Summarise everything recorded for a site: its pages, the buttons and links the user actually uses on each (with CSS selectors), the fields they fill, the API endpoints behind it, common paths between pages, and saved notes. Pass page for one page in detail including its last outline. Read this before automating or restyling a site.
Inputs: site (required), page.
site_notesB
Read or write notes about a site that persist for future sessions and other agents: how things work, where things are, gotchas. Without text it reads them.
Inputs: site (required), text, append.
site_sessionsBRead-only
List recorded sessions for a site, or read one session's timeline step by step.
Inputs: site (required), from, limit, session.
snapshotARead-only
Read the page as an outline of headings, text and interactive elements. Each element you can act on has a ref like [e14]. Take a snapshot before acting and use the refs in click, type and fill_form.
Inputs: tab, maxLines.
start_sessionA
Start working in the user's own browser (their logins and cookies) when no tab is shared yet. mode=window (default) opens a separate window for you, so the user's tabs are left alone; every tab you open in it is yours. mode=current asks to use the tab the user is looking at, for tasks about the page they're on. The user approves in a prompt (up to two minutes). Returns the tab handle and a snapshot.
Inputs: reason (required), url, mode, browser.
typeA
Type into a text field or editable area. Replaces the current value unless append is true.
Inputs: ref (required), text (required), tab, append, +1 more.
upload_fileA
Attach local files to a file input, as if the user picked them.
Inputs: ref (required), paths (required), tab.
video_frameARead-only
Get the current frame of a video on a shared tab as an image. Falls back to a cropped screenshot when the site doesn't allow reading the video.
Inputs: ref (required), tab.
wait_forARead-only
Wait until some text appears or disappears, or for a number of milliseconds.
Inputs: ms, tab, gone, text, +1 more.
wait_for_downloadA
After clicking something that downloads a file (an invoice, a CSV export, a PDF), wait for it to finish and get its path on disk. Downloads that started in the last 15 seconds count, so call it right after the click.
Inputs: tab, browser, timeout_seconds.
wait_for_userA
Hand a shared tab to the user and wait for them. With message, the page shows it with a Done button and brings the tab to the front: use it for CAPTCHAs, 2FA codes, logins, payment confirmation or any choice that is theirs. Without message, it waits for the user to resume a tab they paused (actions on a paused tab fail with a note saying so). Returns when they press Done or Resume, or after the timeout.
Inputs: tab, message, timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 53 tools
Most tools target a clear browser resource or action, and the descriptions give strong boundaries between page reading (snapshot, read_text, screenshot, run_js) and interaction. A few boundaries are softer: network_requests vs. network_request, site_list vs. site_map vs. site_sessions, and save_script vs. install_userscript can require reading descriptions carefully.
Names are consistently lowercase snake_case and mostly follow recognizable verb_noun or category-prefix patterns. There are minor deviations such as bare verbs (click, type, navigate), noun-first site_list/site_sessions, and noun-only network_requests/cookies, but the conventions remain readable and predictable.
The server covers a very broad browser-automation surface, but 53 tools is far beyond a well-scoped set and imposes a significant selection burden. Many tools earn their place functionally, yet the total count is too high for one coherent toolset.
The surface is unusually complete for browser automation: tabs, interaction, page reading, network/console inspection, sessions, styles, scripts, watchers, media, downloads, and site memory are all covered. Minor gaps remain, such as setting/deleting cookies and explicit dialog handling, though run_js can work around many of them.
Maintenance
Related MCP Connectors
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
A real cloud browser for your AI agent. Connect Claude, ChatGPT, Cursor or any MCP client: the agent opens, reads and acts on pages with real mouse and keyboard input, in an isolated session on Browser.lol's servers. You watch live and take over at any time, for example to sign in. Sessions in other countries, an Anonymous Mail inbox for sign-up codes and saved profiles. OAuth sign-in or an API key; needs the Premium plan.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server + Chrome extension that gives AI coding agents control of your real browser with existing sessions, logins, and cookies. Works with Cursor, Claude, Windsurf.24154 npm59MIT
- AlicenseNot gradedqualityBmaintenanceChrome extension + MCP server. Lets coding agents (Claude Code, Codex CLI) drive your real Chrome — sessions intact, 2FA stays with the user. 26 browser tools: form fill on React/CodeMirror/Monaco, privileged fetch that bypasses page CSP, authenticated downloads, in-extension docx parsing. Battle-tested by 400+ hours of real agentic browser work before public v0.9 release.3MIT
- AlicenseNot gradedqualityDmaintenanceChrome extension + MCP bridge that gives Claude control over your real browser via CDP, enabling navigation, clicking, typing, scrolling, screenshots, and JS execution with a visible cursor and tab-bring-to-front.1MIT
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding tools drive the user's own already-logged-in Chrome — clicking, typing, reading pages, taking screenshots, and inspecting cookies, network, and console through the extension rather than a debug port. All communication stays on the machine, with agent-opened tabs grouped and kept out of focus.1 npmISC