Foxhand MCP server
Commit Nov 15, 2026Allows an AI agent to control your local Firefox browser, including managing tabs, interacting with pages, and using your existing logins and sessions.
Also known as hamb1y/foxhand
- Stars
- 9
- Tools
- 45
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MPL-2.0
What is Foxhand MCP?
Foxhand allows an AI agent to control your local Firefox browser, including managing tabs, interacting with pages, and using your existing logins and sessions. It exposes 45 tools, such as tab_query, tab_check_active, tab_create.
Summary generated from the project's README
About Foxhand MCP server
Controlling your existing Firefox browser from an AI agent is what Foxhand enables. Unlike headless browser solutions, this server connects to your actual Firefox profile, allowing an agent to access your open tabs, bookmarks, history, and active login sessions. This makes it possible for an AI to perform tasks on websites where you are already authenticated without needing to manage new credentials.
Developers can connect various MCP clients such as Claude Code, Cursor, Codex, Gemini CLI, and opencode to the local helper. The setup involves installing a Firefox add-on and a small native messaging host on your machine. Communication happens over localhost using a 256-bit bearer token for security. The server provides 45 specific tools for interacting with the web, including commands for managing tabs, clicking elements, typing text, and handling cookies. A visible AI cursor also appears in the browser to show exactly where the agent is interacting with a page.
What you can do with it
- 1Automate authenticated web tasksAn AI agent can use your existing logins to navigate websites and perform actions.
- 2Interact with complex web elementsThe agent can click buttons and fill out forms even on difficult sites with iframes or shadow DOMs.
- 3Monitor AI browser activityYou can watch a visual cursor move around the screen to see what the AI is doing in real time.
- 4Manage browser sessions via CLIDevelopers can use command line tools like Claude Code to control their browser windows and tabs.
Written from the project's README. Every use case is checked against a quote from it.
Foxhand MCP tools 45
Detected from the READMEtab_querytab_check_activetab_createtab_navigatetab_focustab_closetab_pintab_mutewindow_querywindow_createwindow_focuswindow_close
Show all 45 toolsShow fewer tools
page_snapshotpage_textpage_htmlpage_screenshotpage_infopage_findpage_clickpage_typepage_fillpage_selectpage_hoverpage_scrollpage_keypage_waitpage_dragpage_uploadbookmark_querybookmark_createbookmark_removehistory_querydownload_querydownload_startcookie_querycookie_setcookie_removestorage_getstorage_setstorage_removesession_querysession_restoreextension_statusthoughtevent_wait
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehamb1y/foxhand is public and reachablegithub.com/hamb1y/foxhand ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MPL-2.0spdx.org/licenses/MPL-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/hamb1y/foxhand ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model45 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFoxhand
Let an AI agent drive the Firefox you already use: your current profile, your open tabs, your logins. Any MCP client can connect, including Claude Code, Codex, Gemini CLI, opencode and Cursor.
Formerly WebMCP Controller. Renamed so it isn't confused with WebMCP, the proposed standard for websites to expose their own tools to agents. Upgrading? See Moving from WebMCP Controller.
There is no server to start by hand. Firefox launches a small helper app (a native messaging host) when the add-on loads, and the helper serves MCP on your own machine.
Install the add-on from addons.mozilla.org · Website · What's new in 0.5.4
A real capture: an MCP client asked Foxhand to search Wikipedia, then point at the article. The orange bubble is the AI saying what it's doing.
Features
- Your real browser. Works on your current profile, with your tabs, bookmarks, history and logged-in sessions. Not a clean headless browser.
- Local by design. The helper listens on this computer only (
localhost) and every request needs a 256-bit bearer token. Nothing leaves your machine unless the AI tool you connect sends it somewhere. - Visible AI cursor. While the agent works, a cursor glides to whatever it is clicking or typing into, with an orange bubble that says what it is doing. Toggle it from the popup.
- Pause AI. The popup button, or Ctrl+Shift+.,
stops every command until you resume. The toolbar badge shows
IIwhile paused and an orange dot while the AI is working. - 45 tools. Tabs, windows, page reading, screenshots, typing, clicking, dragging, uploads, bookmarks, history, downloads, cookies and a persistent notebook for the agent. See Tools.
- Built for real pages. The snapshot finds what usually needs workarounds: buttons made from plain divs, icon-only and hover-only controls, closed shadow DOM, and iframes from other sites such as cookie banners and sign-in buttons. Typing sends real key presses, so autocomplete, input masks and rich editors work. Page dialogs never freeze an action, and links that open a tab report the new tab.
- Guided setup in your language. A setup page opens on install. The add-on speaks English, Spanish, French, German and Simplified Chinese.
Quick start
-
Install the add-on from the link above. A setup page opens.
-
Install the helper (once per computer), by pasting one line:
- macOS and Linux, in Terminal:
curl -fsSL https://foxhand.pages.dev/download/sh | sh - Windows, in PowerShell:
irm https://foxhand.pages.dev/download/ps | iex
- macOS and Linux, in Terminal:
-
Connect your AI. The setup page (or the toolbar popup's Copy MCP config) gives you the exact command or config. It ticks that step off when your AI sends its first command.
Claude Code, for example:
claude mcp add -s user -t http firefox http://localhost:8901/mcp -H "Authorization: Bearer <token>"
The settings page (toolbar icon → Settings) also has commands and snippets for the other clients. The generic config looks like this:
{
"mcpServers": {
"firefox": {
"type": "http",
"url": "http://localhost:8901/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
- Codex (
~/.codex/config.toml):[mcp_servers.firefox] url = "http://localhost:8901/mcp" http_headers = { Authorization = "Bearer <token>" } - Gemini CLI:
gemini mcp add --scope user --transport http firefox http://localhost:8901/mcp --header "Authorization: Bearer <token>" - opencode:
{"mcp":{"firefox":{"type":"remote","url":"http://localhost:8901/mcp","headers":{"Authorization":"Bearer <token>"}}}} - stdio-only clients:
npx -y mcp-remote http://localhost:8901/mcp --header "Authorization: Bearer <token>"
Check the connection from a shell:
curl http://localhost:8901/health
# {"ok":true,"extensionConnected":true,"version":"0.5.4"}
Architecture
Firefox (WebExtension) Helper (native messaging host) AI client
+----------------------+ stdio +-----------------------------+ HTTP +--------------+
| background.js | <---------> | foxhand-host | <-----> | Claude Code, |
| content scripts | Firefox | serves MCP on localhost | POST | Codex, ... |
| (tabs, page, cursor)| starts it | Bearer-token authenticated | /mcp | |
+----------------------+ +-----------------------------+ +--------------+
- The add-on owns the settings. It generates the token on first run and
sends
{token, port, bind}to the helper. Defaults: port 8901, bind 127.0.0.1 (the helper also listens on[::1], solocalhostworks whichever address a client tries first). - AI clients talk to the helper over MCP Streamable HTTP,
POST /mcp, withAuthorization: Bearer <token>. Two endpoints need no token:GET /healthandGET /. - The helper runs as long as the add-on runs. Close Firefox and the MCP endpoint goes away.
Why an extension: a WebExtension gets every tab, window, bookmark and cookie of the profile you use, which the remote-debugging protocol does not offer. Why a native host: extensions cannot listen on ports, and native messaging is the sanctioned way for an add-on to reach a local program.
Installing the helper
Windows, in PowerShell:
irm https://foxhand.pages.dev/download/ps | iex
(In Command Prompt, type powershell first.)
macOS, Linux, WSL, in a terminal (inside WSL it installs the Windows helper):
curl -fsSL https://foxhand.pages.dev/download/sh | sh
The script picks the x64 or arm64 binary, checks its SHA-256 against the
release's SHA256SUMS and runs install. On macOS there's no Gatekeeper
prompt: the binary carries an ad-hoc signature, and the script re-signs it if
that doesn't verify. These are the same scripts as install.sh and
install.ps1 in each release, served from this repo's GitHub Pages.
Prefer to do it by hand? Download foxhand-host-<os>-<arch> from the
releases page, then run it
with install: on Windows, double-click the .exe; on macOS, run
xattr -c foxhand-host-darwin-arm64 first, because a browser download is
quarantined.
install copies the helper to a per-user folder and registers it with Firefox.
No admin rights needed.
| OS | Helper goes to | Registered via |
|---|---|---|
| Windows | %LOCALAPPDATA%\foxhand\ |
HKCU\Software\Mozilla\NativeMessagingHosts\webmcp_controller |
| macOS | ~/Library/Application Support/foxhand/ |
~/Library/Application Support/Mozilla/NativeMessagingHosts/ |
| Linux | ~/.local/share/foxhand/ |
~/.mozilla/native-messaging-hosts/ (and the Snap path) |
Other commands: status, uninstall, version, help.
To update, run the install command again. Firefox switches to the new helper within a few seconds, with no restart.
Moving from WebMCP Controller
Foxhand is the same add-on under a new name: AMO updates it in place and your
settings and token stay. Run the install command once more. It installs
foxhand-host, makes the running WebMCP Controller helper hand over to it, and
the old webmcp-controller folder is removed shortly after. Your AI's MCP
config keeps working; re-copying it gives you the shorter localhost URL.
Running from a source checkout
npm install
npm run install-host # registers a Node-based helper with Firefox
Then load extension/manifest.json as a temporary add-on at
about:debugging#/runtime/this-firefox → Load Temporary Add-on….
Harness inside WSL, Firefox on Windows
WSL2's default NAT networking cannot reach Windows' 127.0.0.1. The easy path:
- Toolbar icon → Settings → Connect your AI. Pick your AI, then set Runs in to WSL. This allows AIs in WSL to connect.
- If Windows Firewall asks about
foxhand-host, allow it on Private networks. - Copy the config and paste it inside WSL. The Claude Code and Gemini commands look up the Windows address on each run, so they survive reboots. Config files hold the current address, so copy them again if the connection drops after a Windows restart.
The helper then listens on the vEthernet (WSL) adapter only, not your LAN.
Alternatively, enable WSL mirrored networking (networkingMode=mirrored under
[wsl2] in %UserProfile%\.wslconfig, then wsl --shutdown). After that,
127.0.0.1:8901 works from WSL as-is.
AI cursor
While the agent works, an animated cursor on the page glides to what it is clicking or typing into. A bubble beside it says what it is doing.
- Actions (
page_click,page_type, ...): the cursor moves to the target, then clicks with a ripple. The bubble describes the action, such as "Clicking “Sign in”", in the browser's language. Typed passwords are never echoed. thought: the agent can explain its reasoning, for example"Opening the pricing page to compare plans". The note shows right away and stays on the next page action (read or act) within 30 seconds, then the cursor goes back to describing actions itself.- The cursor is drawn in a closed shadow root with
pointer-events: none. It never blocks real input or appears inpage_htmlorpage_snapshot, and it is hidden whilepage_screenshotcaptures. - It fades after 8 seconds idle. Turn it off in the popup (Show AI cursor) or in Settings (Show the AI cursor). It is on by default.
Cursor shapes are Bibata by ful1e5 (GPL-3.0).
Tools
Tool names match registerTool( in mcp-server/src/tools/*.ts. They follow
<thing>_<verb>: tab_query, page_click, cookie_set.
Page tools find an element by ref (from page_snapshot), by name (its
visible text or label, with optional role and nth), by CSS selector, or
by x,y viewport coordinates for canvas apps. When a name matches several
elements, the AMBIGUOUS error lists them.
| Tool | What it does |
|---|---|
tab_query |
List tabs (query: "*" or nothing) or find them by text in the URL or title, URL/title regex and state flags. |
tab_check_active |
The tab the user is looking at (id, url, title, window). |
tab_create |
Open a tab. Adds https:// when the scheme is missing (http:// for localhost and IP addresses). duplicateOf copies an existing tab. |
tab_navigate |
Load a URL, or go: "back", "forward" or "reload". |
tab_focus |
Switch to a tab and bring its window forward. |
tab_close |
Close one tab (tabId), several (tabIds) or the active one. Needs confirm:true. |
tab_pin |
Pin a tab, or unpin it with pinned:false. |
tab_mute |
Mute a tab, or unmute it with muted:false. |
window_query |
List windows (id, focused, private, tab count). |
window_create |
Open a new window, optionally at a URL. |
window_focus |
Bring a window to the front. |
window_close |
Close a window and its tabs. Needs confirm:true. |
| Tool | What it does |
|---|---|
page_snapshot |
Outline of the page with [ref=N] for each element, nested under its landmark, dialog, form, row or list item. Includes buttons made from plain divs (clickable), icon-only and hover-only controls, open and closed shadow DOM, and iframes from any site. An open modal or overlay is listed first. within reads one region, viewportOnly just what's on screen. |
page_text |
Visible text, iframes included, in chunks for long pages (offset, nextOffset), optionally within one region. format: "markdown" keeps headings, lists, tables and link URLs. |
page_html |
HTML of the page or of one part (selector or within). |
page_screenshot |
The visible area, one element, or the whole page (fullPage). format: "jpeg" and scale make it smaller. |
page_info |
URL, title and load state. |
page_find |
Find text (also split across elements, and in iframes), with a snippet, the ref to click and whether it's off screen. |
| Tool | What it does |
|---|---|
page_click |
Click an element or a point. Reports what changed, tabs the click opened (openedTabs) and the new URL. |
page_type |
Type key by key into a field (named by its label or placeholder), textarea or rich editor (Lexical, ProseMirror, Slate, CKEditor), so autocomplete and input masks work. Also sets checkboxes and selects. Can submit through the form's button, a composer's Send button, or Enter. |
page_fill |
Fill several fields in one call. Every field is checked first, so one bad field changes nothing. |
page_select |
Choose options in a <select> or a custom combobox or listbox. A miss lists the options. |
page_hover |
Send hover events for JS menus and tooltips. CSS :hover cannot be triggered. |
page_scroll |
Scroll the page, an element into view, or inside a scroller. Finds the inner scroller of chat apps. |
page_key |
Press a key with modifiers. Performs the default action (Tab, Enter, Space, editing keys) when the page doesn't. |
page_wait |
Wait for text or an element to appear, for it to go (gone:true, for spinners), for the address to change (urlContains), or for the page to settle. |
page_drag |
Drag an element or point onto another: sortable lists, sliders, map panning. |
page_upload |
Attach files to a file input or drop zone. The agent supplies the contents; files on disk can't be read. |
Page dialogs never block an action. While the AI acts, alert() is
acknowledged and confirm()/prompt() are answered Cancel; the result
lists what the page asked (dialogs). To answer OK, repeat the action with
dialog: "accept" (and promptText for a prompt).
| Tool | What it does |
|---|---|
bookmark_query |
Find bookmarks by title or URL. |
bookmark_create |
Create a bookmark or folder. |
bookmark_remove |
Delete a bookmark by id. Needs confirm:true. |
history_query |
Search browsing history (all of it unless startTime is given). |
download_query |
List downloads with the file's path on disk, state, size, progress and why one failed. |
download_start |
Download a URL into the downloads folder with the browser's cookies, wait for it and return the path. |
cookie_query |
Cookies a page sees, from its container or private store, including partitioned ones. |
cookie_set |
Create or overwrite a cookie. |
cookie_remove |
Delete a cookie by name. Needs confirm:true. |
storage_get |
Read a key, or list keys. |
storage_set |
Save a value. |
storage_remove |
Delete a key. |
session_query |
Recently closed tabs and windows. |
session_restore |
Reopen a recently closed tab or window. |
The storage_* tools default to the agent's own notebook (area: "agent"):
JSON values kept in the add-on's storage across pages and Firefox restarts, up
to 1000 keys. area: "local" and "session" read and write the page's own
localStorage and sessionStorage.
| Tool | What it does |
|---|---|
extension_status |
Whether the add-on is connected, plus profile details. |
thought |
Show a note in the AI cursor bubble. It stays on the next page action. |
event_wait |
Wait for an event such as tab.updated, tab.removed, tab.activated or download.done. Pass the result's seq as afterSeq to catch events between calls. |
Limits and safety
- Local only by default. The helper binds
127.0.0.1. Every MCP request needs the 256-bit bearer token, compared in constant time. Rotate the token in Settings (New) and re-copy the config. - Browser checks. Requests with a foreign
HostorOriginheader get a 403, which blocks DNS rebinding and cross-site requests. The token is checked before the body is read. - Cancellation. Closing the HTTP request, or sending
notifications/cancelled, stops the command in Firefox too. - Confirm guard.
tab_close,window_close,bookmark_removeandcookie_removerefuse to run withoutconfirm:true. - No password access. No tool reads saved logins or the Firefox password manager.
- No browser chrome in screenshots.
page_screenshotcaptures page content only, not the toolbar or other browser UI. - Prompt injection is real. A web page can try to instruct the agent. Don't point it at anything you wouldn't let a stranger click through.
Troubleshooting
- "Helper app not installed." The install step didn't run, or it registered
somewhere this Firefox doesn't read. Run
foxhand-host statusto see where it registered, then press Retry in the popup.- Snap Firefox on Ubuntu reads
~/snap/firefox/common/.mozilla/native-messaging-hosts. The installer writes there too. - Flatpak Firefox can't run native helpers without extra sandbox overrides. Use the deb or tarball build instead. The installer warns when it finds one.
- Snap Firefox on Ubuntu reads
- "Helper is too old" or "add-on is too old." Run the install command again, or update the add-on, as the popup says.
- Worked before 0.3.4, "not installed" now. Everything was renamed from
firefox-mcp. Install the new add-on and run the install command once. The installer removes the old registration. Delete the oldfirefox-mcpfolder after closing Firefox. - A PDF tab says it can't be read. Firefox's PDF viewer doesn't let add-ons
in. Use
page_screenshot, or open the PDF in another app. - "Port 8901 is already in use." Another app, or this add-on in a second Firefox profile, holds the port. In Settings, choose another port, save, then re-copy the MCP config.
- 401 Unauthorized. The token changed. Re-copy the config.
- Temporary add-on disappeared after a restart. Temporary add-ons unload
when Firefox closes. Reload it from
about:debugging, or install the signed add-on. RESTRICTED_PAGE. Page-content tools (page_*) don't run onabout:,chrome:,resource:,moz-extension:,view-source:,jar:,data:orblob:pages, or onaddons.mozilla.org, or in PDFs. Firefox doesn't allow scripting there.REF_STALEorREF_NOT_FOUND. Refs frompage_snapshotbelong to one page load. Pass the snapshot'sgenerationwith the refs. After the page changes or navigates, take a new snapshot.PAYLOAD_TOO_LARGE. Firefox limits native messages to 1 MB. Ask for less text per call.- Helper logs. The helper writes to stderr, which Firefox shows in the
Browser Console (Ctrl+Shift+J) with a
[foxhand]prefix, and tofoxhand-host.lognext to the helper.
Announcements
The add-on checks https://foxhand.pages.dev/endpoint/announcement on
startup and every four hours for occasional announcements. Each announcement
opens once per Firefox profile; shown IDs stay in local extension storage across
restarts and updates. The endpoint receives ordinary HTTPS connection metadata
(such as the IP address), but no credentials, browsing data, or shown IDs.
Announcement HTML is limited to basic formatting and HTTPS links; scripts and
embedded content are removed. See publishing announcements.
Development
npm install
npm run build && npm run typecheck
npm test # everything below
node test/e2e.mjs # real background.js (mocked browser APIs) and real helper over native messaging and HTTP
MISSING=1 node test/e2e.mjs # the "helper not installed" flow
node test/host.mjs # helper: reconfiguration, Host/Origin checks, size limits, cancellation, protocol mismatch
npx playwright install firefox && node test/content.mjs # content scripts in real Firefox
node test/e2e.mjs dist/host/foxhand-host-linux-x64 # same, against a compiled helper
node test/live.mjs # real Firefox + this add-on + the helper, all 45 tools over MCP
node test/live.mjs --real # ... plus a few real websites
node scripts/i18n.mjs --check # every translation complete and generated
npx web-ext@8 lint -s extension
node scripts/site-shots.mjs # retake the website's screenshots (site/shots/) from a real run
test/live.mjs starts your installed Firefox with a throwaway profile and a
throwaway home folder (your own profile and helper are untouched), installs the
add-on over WebDriver BiDi, and drives it through a real MCP client: fixtures
for forms, chat boxes, dialogs, iframes, shadow DOM, new tabs, sleeping tabs,
pausing, cancellation and helper crashes. CI runs it on Linux, macOS (Apple
silicon and Intel) and Windows (x64 and ARM) against the helper installed by
the one-line installers (.github/workflows/platforms.yml).
Translations. i18n/<locale>.json holds each language's strings
($1 for values). node scripts/i18n.mjs writes extension/_locales;
the generated files are committed, so the add-on still has no build step.
Messages meant for the AI stay in English.
The add-on and helper share one version number (package.json,
manifest.json, shared/src/version.ts). A separate wire PROTOCOL number
changes only on breaking bridge changes. On connect the two sides exchange both
numbers. A version mismatch gets a warning and keeps working. A protocol
mismatch tells you which side needs updating.
Foxhand MCP questions
What tools does Foxhand MCP provide?
It exposes 45 tools, including tab_query, tab_check_active, tab_create, tab_navigate, tab_focus.
Does Foxhand use a headless browser?
No, it works on your real Firefox profile, including your current tabs, bookmarks, history, and logged-in sessions.
How do I install the helper for Foxhand?
You can install it via a single command in your terminal: use curl for macOS/Linux or irm for Windows PowerShell.
Is my data safe when using Foxhand?
Yes, it is local by design; the helper only listens on localhost and requires a 256-bit bearer token for requests.
Can I see what the AI is doing in my browser?
Yes, a visible AI cursor glides to where the agent is clicking or typing, accompanied by an orange bubble describing the action.