Camoufox MCP Server

An MCP (Model Context Protocol) server that provides browser automation capabilities using Camoufox, a privacy-focused Firefox fork with advanced anti-detection features.

Quick Install

Use the published npm package unless you are developing this repository locally.

Claude Code CLI

claude mcp add camoufox -- npx -y camoufox-mcp-server@latest

For a shared project-scoped Claude Code config:

claude mcp add --scope project camoufox -- npx -y camoufox-mcp-server@latest

Verify with /mcp inside Claude Code.

Codex CLI

codex mcp add camoufox -- npx -y camoufox-mcp-server@latest

Codex stores MCP servers in ~/.codex/config.toml by default. Verify with /mcp inside Codex.

Agent Skill and Plugin Bundle

Use these when you want the camoufox skill plus the packaged MCP server config. If you only need the MCP server, use the Claude Code or Codex MCP commands above. Bare npx -y camoufox-mcp-server@latest remains safe by default. The packaged plugin bundle enables CAMOUFOX_MCP_ALLOW_UNSAFE_OPTIONS=1 so the skill can use firefox_user_prefs, args, and exclude_addons for hard-site tuning.

OpenClaw

Register the MCP server directly. This works today with no registry publish (--arg is singular and repeatable; the --env flag enables the unsafe-option tuning):

openclaw mcp add camoufox --command npx --arg -y --arg camoufox-mcp-server@latest --env CAMOUFOX_MCP_ALLOW_UNSAFE_OPTIONS=1
openclaw mcp list

OpenClaw exposes the tools with provider-safe names such as camoufox__browse.

The ClawHub bundle (skill + config in one install) publishes on the next tagged release. Once it is live, you can instead run:

openclaw plugins install clawhub:@whit3rabbit/camoufox-mcp
openclaw plugins inspect camoufox
openclaw plugins doctor
openclaw gateway restart

Claude Code

Install the plugin from this repo's marketplace:

/plugin marketplace add whit3rabbit/camoufox-mcp
/plugin install camoufox@camoufox-mcp

Restart Claude Code or start a new session after installing.

Codex

Install the plugin from this repo's marketplace:

codex plugin marketplace add whit3rabbit/camoufox-mcp
codex plugin add camoufox@camoufox-mcp

Restart Codex or start a new thread after installing.

Hermes

Two commands: install the skill, then register the MCP server (Hermes skill installs do not auto-register MCP servers).

hermes skills install whit3rabbit/camoufox-mcp/plugins/camoufox/skills/camoufox
hermes mcp add camoufox --command npx --env CAMOUFOX_MCP_ALLOW_UNSAFE_OPTIONS=1 --args -y camoufox-mcp-server@latest

Do not run hermes plugins install … for this repo. Hermes plugins are Python packages with a root plugin.yaml; this repo has neither, so it clones but is rejected as "not a valid plugin." Use the two commands above.

Hermes treats --args as plain argv tokens and it must be the last option. Do not pass a JSON array string there. In ~/.hermes/config.yaml, env must be a mapping (KEY: "value"), not a list. Verify with:

hermes mcp list
hermes mcp test camoufox

First browse on a fresh machine needs the browser binary once (~780MB); if a call reports it is missing, run npx -y camoufox-js fetch and retry.

Restart Hermes from a separate terminal after changing MCP config. Hermes namespaces MCP tools with an mcp__camoufox… prefix (commonly mcp__camoufox__browse); use whatever name your tool list shows, and confirm the status tool reports unsafeOptionsAllowed: true. browser_navigate is Hermes' own built-in browser tool, not Camoufox.

For local-clone installs and additional hosts, see Configuration for AI assistants.

opencode

Add this to opencode.json in your project or to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "camoufox": {
      "type": "local",
      "command": ["npx", "-y", "camoufox-mcp-server@latest"],
      "enabled": true
    }
  }
}

Verify with:

opencode mcp list

Pi Coding Agent

Install the MCP adapter, then add Camoufox to .mcp.json or ~/.config/mcp/mcp.json:

pi install npm:pi-mcp-adapter

{
  "mcpServers": {
    "camoufox": {
      "command": "npx",
      "args": ["-y", "camoufox-mcp-server@latest"]
    }
  }
}

Try Camoufox

Once configured, ask your assistant for browser work in plain language:

Use Camoufox to browse https://example.com and return metadata only.

Use Camoufox to inspect the interactive elements on https://example.com.

Use Camoufox to open https://example.com, take a screenshot, and summarize the visible page.

Use Camoufox to browse https://developer.mozilla.org with images blocked and WebRTC blocked.

Features

• Advanced anti-detection: rotating OS fingerprints, realistic cursor movements, and browser fingerprint spoofing.
• Enhanced parameters: configurable wait strategies, timeouts, viewport dimensions, diagnostics, and screenshots.
• Cross-platform: works on Windows, macOS, and Linux, including Docker.
• Privacy controls: SSRF protections, WebRTC blocking, WebGL blocking, image blocking, proxy support, and bounded output.
• Session tools: short-lived isolated browser sessions with challenge pause/resume support.

Requirements

• Node.js 22 or higher
• Python 3.x for running tests

Versioning

camoufox-js (0.10.2) and playwright-core (1.59.0) are pinned, fetching the Camoufox 135.0.1-beta.24 browser build. playwright-core is a direct pinned dependency (not just an overrides entry) because npm overrides only bind the root project: without a direct pin, npx/global installs let camoufox-js's peer float playwright-core to the latest, and playwright-core 1.60+ is incompatible with the Camoufox browser (1.60 breaks a navigation guard; 1.61 sends an isMobile viewport option Firefox/Camoufox rejects). The pins are the newest combination that passes the full test suite. Run npm run doctor to check them end-to-end, and do not loosen them without re-running npm run test:all.

Documentation

• Configuration for AI assistants
• Usage examples
• Tool parameters
• Server policy
• Development
• Troubleshooting
• Privacy and security

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome. Please submit a pull request or open an issue for bugs and feature requests.

Acknowledgments

• Built with Camoufox
• Uses the Model Context Protocol
• Powered by Playwright

Support

If you encounter issues, check Troubleshooting first, then open an issue on GitHub with logs and environment details.