foxhand
Let an AI agent drive your real Firefox over MCP: your tabs, your logins, on your machine. Formerly WebMCP Controller.
Install / Use
claude mcp add hamb1y -- npx -y github:hamb1y/foxhandIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of foxhand
foxhand scores 81/100 on our quality scale, 2331st of 2,769 Automation skills we index.
Its MCP Server is 26 KB long, well organised into 19 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so foxhand is actively maintained.
- It is released under MPL-2.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below). An AI review of the same text found nothing harmful.
- noteInstalls by piping a downloaded script into a shellline 57
- macOS and Linux, in Terminal: `curl -fsSL https://hamb1y.github.io/foxhand/sh | sh` - noteInstalls by piping a downloaded script into a shellline 58
- Windows, in PowerShell: `irm https://hamb1y.github.io/foxhand/ps | iex` - noteInstalls by piping a downloaded script into a shellline 139
irm https://hamb1y.github.io/foxhand/ps | iex
AI review by kimi-k2.7-code on 2026-11-13. Automated pattern scan on 2026-11-13. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
foxhand compared with similar skills
All 4 of these similar skills score higher than foxhand; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| foxhand (this skill)by hamb1y | 81 | 10 | 2d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.7k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install foxhand?
- Run
claude mcp add hamb1y -- npx -y github:hamb1y/foxhand. The install tabs above show the steps for each supported agent. - Which AI agents does foxhand work with?
- It is written for Claude Code, Claude Desktop, Gemini CLI and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is foxhand safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below). An AI review of the same text found nothing harmful. It is MPL-2.0-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is foxhand still maintained?
- The repository was last updated 2 days ago, so foxhand is actively maintained.
Skill content
View source 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
<img src="site/shots/cursor.webp" alt="A Wikipedia article on the red panda. The AI cursor rests on the title with an orange bubble that reads: Reading up on the red panda, the animal Firefox is named after.">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 <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd>,
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://hamb1y.github.io/foxhand/sh | sh - Windows, in PowerShell:
irm https://hamb1y.github.io/foxhand/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>" }
}
}
}
<details>
<summary>Other clients</summary>
- 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://hamb1y.github.io/foxhand/ps | iex
(In Command Prompt, type powershell first.)
macOS, Linux, WSL, in a terminal (inside WSL it installs the Windows helper):
curl -fsSL https://hamb1y.github.io/foxhand/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 elem
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
