Provides a self-hosted stealth browser engine and Rust runtime that allows AI agents to navigate the web without being detected by anti-bot systems.
Also known as autokeren/ghostfox
- Stars
- 19
- Tools
- —
- Downloads, 30 days
- 1,792
- Latest version
- 0.9.2
- Last commit
- Nov 13, 2026
- License
- MIT
What is Ghostfox MCP?
Ghostfox provides a self-hosted stealth browser engine and Rust runtime that allows AI agents to navigate the web without being detected by anti-bot systems.
Summary generated from the project's README
About Ghostfox MCP server
Developers building AI agents that need to browse the web without being blocked by anti-bot systems can use Ghostfox. It provides a self-hosted browser stack consisting of a fingerprint-coherent stealth engine and a Rust-based MCP runtime. Unlike hosted stealth browsers that route sessions through third-party clouds, this setup allows you to own the entire stack, including a Firefox fork with C++ level anti-detect patches.
Users can deploy the server via Docker, npm, PyPI, or direct binary installation. The system supports creating coherent identities, such as Android personas with specific GPU and font profiles, to ensure consistent browser fingerprints. It includes a native captcha suite that solves various families like hCaptcha and GeeTest using local models rather than paid cloud services. The server offers two toolset tiers, with the core set providing 26 essential tools for reading and acting on pages, while the full set expands to 72 tools including network interception and identity morphing.
What you can do with it
- 1Bypassing bot detectionAn AI agent can navigate websites that typically trigger Cloudflare 403 errors by using engine-level spoofing.
- 2Solving captchas locallyA developer can instruct an agent to solve complex hCaptcha or GeeTest challenges without using external paid services.
- 3Maintaining persistent sessionsYou can create and migrate browser profiles that keep cookies and identities intact across restarts.
Written from the project's README. Every use case is checked against a quote from it.
How to install Ghostfox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Ghostfox MCP in Claude Code
$ claude mcp add ghostfox -- uvx ghostfoxInstall Ghostfox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ghostfox": {
"command": "uvx",
"args": [
"ghostfox"
]
}
}
}Install Ghostfox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"ghostfox": {
"type": "stdio",
"command": "uvx",
"args": [
"ghostfox"
]
}
}
}Install Ghostfox MCP in VS Code CLI
$ code --add-mcp '{"name":"ghostfox","type":"stdio","command":"uvx","args":["ghostfox"]}'Install Ghostfox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ghostfox": {
"command": "uvx",
"args": [
"ghostfox"
]
}
}
}Install Ghostfox MCP in Codex
$ codex mcp add ghostfox -- uvx ghostfoxInstall Ghostfox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.ghostfox] command = "uvx" args = ["ghostfox"]
Install Ghostfox MCP in Gemini CLI
$ gemini mcp add -s user ghostfox uvx -- ghostfoxInstall Ghostfox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ghostfox": {
"command": "uvx",
"args": [
"ghostfox"
]
}
}
}Configuration
GHOSTFOX_HOME
| Name | Description | |
|---|---|---|
| GHOSTFOX_HOME | — |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubGhostfox
The agent-native stealth browser you can own.
Self-hosted · Open source · MCP-first · Engine-level anti-detect
AI agents get blocked. Headless Chrome triggers Cloudflare 403s on ~20% of the web, and hosted "stealth browsers" route your agent's cookies, identities and sessions through someone else's cloud.
Ghostfox is the alternative: a complete browser stack you run yourself — a fingerprint-coherent stealth engine plus a Rust MCP runtime, in one repo.
Firefox (MPL-2.0)
└─ Camoufox (anti-detect patches, by daijro)
└─ Ghostfox engine engine/ — spoofing at the C++ level
└─ Ghostfox runtime runtime/ — Rust: sessions, identities, MCP
| Ghostfox | Hosted stealth (Browserbase etc.) | playwright-mcp | Anti-detect suites (Multilogin etc.) | |
|---|---|---|---|---|
| Self-hosted | ✓ | ✗ | ✓ | partially |
| Open source | ✓ | ✗ | ✓ | ✗ |
| MCP-native | ✓ | ✓ | ✓ | ✗ |
| Engine-level anti-detect | ✓ (C++/Firefox) | vendor partnerships | ✗ | ✓ (closed) |
| Coherent identities + auditor | ✓ | ✗ | ✗ | partial |
| Runtime language | Rust | — | Node | — |
The moat — why this isn't just another wrapper.
- We own the engine. The anti-detect lives in C++ patches inside our own Firefox fork — not in injected JS that detectors can read. Upstream Camoufox has signaled partially-closed patches ahead; wrappers inherit that risk, a fork that owns its engine doesn't.
- A living proof corpus. Every claim here has a receipt: bilibili icon-click ×6, hCaptcha on production signups, TikTok OAuth+OTP live, 500/500 identity audits, Docker E2E. Features get copied in a week — verified history can't be.
- Agent-native ergonomics. 43 coherent MCP tools, fire-then-verify
receipts, evidence recording, and a playbook (
AGENTS.md) distilled from real runs. Agents (and their prompts) build habits on this surface — switching costs are real. - Canonical distribution. PyPI, npm, GHCR and the official MCP Registry under one name, with the docs, benchmarks and changelogs to back it. Forks will exist; the verified trunk is here.
Captcha suite — 8 families, solved on-device (v0.6.7+). The runtime ships native MCP solvers with local models — no paid captcha farms, no cloud, no browser rent:
| Family | Native tool | How |
|---|---|---|
| GeeTest slide / v4 radar | page_geetest_slide |
bg-vs-fullbg diff + largest-blob gap detection |
| GeeTest icon-click (文字点选) | page_geetest_click |
custom-trained YOLOv8s + siamese similarity (rten, CPU) |
| Rotate | page_captcha_rotate |
24-angle sweep + programmatic verdict |
| Normal OCR | page_captcha_ocr |
ported ddddocr (CRNN+LSTM, onnxruntime) |
| hCaptcha | page_hcaptcha |
layout router + 553-model QIN2DIM zoo + optional vision-model ensemble |
| Cloudflare Turnstile / TikTok | captcha_solve + behavioral recipes |
proven playbooks in AGENTS.md §6b–6e |
E2E-verified against production sites (not vendor demos): bilibili icon-click ×6 "Verification Succeeded", hCaptcha on real signups (dashboard.hcaptcha.com, dosya.co), TikTok OAuth+OTP live session.
Debug cortex — page tools that tell you WHY (v0.7). Agents stop guessing when a page misbehaves:
page_console— everyconsole.log/warn/errorsince loadpage_errors— uncaught JS exceptions with stack tracespage_network_start/read/body— request/response capture with body fetch
That's the DevTools trio, exposed over MCP.
Multi-model vision (optional). page_vision + page_ocr +
page_match_image + page_pixels + page_contrast — wire any
vision-capable model (Cloudflare Workers AI, GLM, Qwen, ...) as
cross-checks for grid puzzles and layout questions. Keys are optional;
the native solvers above run fully local.
Native-sourced observation — page_a11y {"native": true} reads the
engine's OWN accessibility tree (Gecko's DocAccessible walk — the
ariaSnapshot plumbing), so page scripts cannot tamper with what you see:
shadow DOM, iframes and ARIA semantics handled by Gecko itself, richer
states (focused/required/checked/expanded/disabled/level). Native refs
are observation handles; acting goes through role+name anchors or the
JS-walk source.
Eyes for agents — page_a11y. One call returns every visible interactive
element with a stable ref, semantic role, accessible name, live value —
piercing shadow DOM and same-origin iframes, so web-component UIs
(Reddit, modern frameworks) are fully visible. The snapshot also reports
login_state (logged-in / logged-out / unknown), page URL and title —
agents check session health before acting, not after failing.
Agents act by ref: page_click_ref e38, page_type_ref e21 "text" — no CSS
selectors needed. Rich editors (Lexical, Draft, ProseMirror) are handled via
editor-native input paths with fire-then-verify receipts. page_wait_for
replaces manual sleeps. page_read_ref gives full untruncated values.
page_upload_file bypasses native file pickers.
Android personas too — session_create {"platform": "android"} gives
portrait screens, Adreno/Mali GPUs, Android font stacks and Firefox-on-Android
UAs, all audited like desktop identities (500/500 coherent, see
runtime/docs).
One identity, no contradictions. Identities are generated from coherent device presets (platform, screen, GPU, fonts that actually ship together), injected at the engine level, and audited before use — a spoofed browser's worst enemy is itself saying "4 cores on a MacBook".
Quickstart
Pick a distribution:
# Python (Linux x86_64)
pip install ghostfox
python -c "import ghostfox; ghostfox.install_engine(); ghostfox.install_runtime()"
# npm / any MCP host
npm install -g ghostfox # or: npx ghostfox install
{
"mcpServers": {
"ghostfox": { "command": "npx", "args": ["-y", "ghostfox", "mcp"] }
}
}
# Docker (engine + MCP runtime, ubuntu:24.04 base)
docker run -i --rm ghcr.io/autokeren/ghostfox:v0.7.2
# or one-line install of the binary stack:
curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash
# Windows (PowerShell):
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/autokeren/ghostfox/main/install.ps1 | iex"
Also listed on the official
MCP Registry
(io.github.autokeren/ghostfox) — one-click add in registry-aware clients.
From source:
# 1) Get the engine (prebuilt) and unpack it somewhere, e.g. /opt
unzip ghostfox-<ver>-lin.x86_64.zip -d /opt/ghostfox
# 2) Build the runtime
git clone https://github.com/autokeren/ghostfox.git
cd ghostfox/runtime
cargo build --release
{
"mcpServers": {
"ghostfox": {
"command": "/path/to/ghostfox/runtime/target/release/ghostfox-mcp",
"env": { "GHOSTFOX_HOME": "/opt/ghostfox" }
}
}
}
Then the agent can: session_create → page_open → page_a11y → act by ref.
Portable sessions. session_create accepts profile_dir for persistent
profiles: cookies, storage and the identity TOML live together in one place,
so a login survives restarts. Migrating a session from another
Camoufox-lineage browser? Copy the cookies and match the identity to the
origin device (platform, timezone, locale, screen) — a session that
suddenly changes identity looks like an impossible login and anti-fraud
systems revoke it. Proven flow, see AGENTS.md §8.
Full tool surface (71 tools) — two tiers, one binary:
core(default): 26 curated tools — the golden loop (read → act → verify) plus debugging essentials, zero overlapping variants. This is what agents and registry inspectors see out of the box: an efficient, disambiguated surface (each tool's description says when to prefer it).full: all 71 tools — captcha families, pixel/vision tiers, network interception, WebSocket capture/inject/block, identity morph, chrome-mode, Android, page_download (browser-identity media harvesting). Run the server withGHOSTFOX_TOOLSET=full.
The server also publishes instructions (a decision tree agents read before choosing tools) — the disambiguation layer for both tiers.
| Category | Tools |
|---|---|
| Session | session_create · session_pages · session_me |
| See | page_a11y (semantic + login_state + shadow DOM/iframe) · page_extract (typed, token-efficient a11y filters) · page_snapshot · page_screenshot · page_read_ref (full value) · page_diff (observeDiff: what changed since the last snapshot) · page_mutations (M3: unhookable DOM-change whispers) · page_a11y_events (M3: the a11y tree as a stream — focus/text/state/live-region events, the incremental diff) |
| Wait | page_wait_for (poll until visible) · page_dismiss_modal · page_wait_stable (render-settled) · page_wait_visual (M3.5: refresh-driver visual stability — the sleep killer) |
| Act | page_click_ref · page_click_native (trusted a11y-bounds click: scroll-first, DOM-proof coordinates) · page_click_at (raw trusted coords — no a11y resolution) · page_type_ref · page_click · page_type · page_fill · page_press · page_drag · page_move_to · page_upload_file · page_init_script · page_a11y_set_text (AT-native text input — the Flutter route) |
| Captcha | captcha_solve · page_geetest_slide · page_geetest_click · page_captcha_rotate · page_captcha_ocr · page_hcaptcha · page_captcha_vision (host-VLM reader for warped text captchas) |
| Network broker | page_network_intercept (hold every request) · page_network_resume (modify url/method/headers/postData) · page_network_abort (block) · page_network_fulfill (mock the response) |
| Debug | page_console · page_errors · page_network_start · page_network_read (per-request DNS/TLS/TTFB timing) · page_network_body · page_frame_stats (M3.5: jank detector — frame-cadence stats) · page_timing_report (M3.5: nav-timing + paint) · page_ws_frames (M3: the WebSocket stream — sockets + frames both directions) · page_ws_send (M3: WS injection — client→server message) · page_ws_block (M3: WS blocking — drop frames both directions) · page_ui_audit (M5: visual QA of the rendered UI) |
| Vision | page_vision · page_ocr · page_match_image · page_pixels (compositor pixels — region/semantic/ref, no toDataURL) · page_contrast |
| Inspect | page_eval · page_open · page_comment |
| Harvest | page_download (media through the browser identity — cookies, TLS fingerprint, referer; streams to <session>/downloads/) |
| Identity | identity_generate · identity_audit · identity_morph (stop→relaunch→swap identity without losing the session) |
| Body sense | page_proprio (M4: honest body state — focus, selection/caret, scrollers) · page_cookie_events (M4: cookie/session heartbeat — auth-cookie deletion = earliest session-death signal) · session_vitals (M4.5: per-process CPU/memory) |
| Recipes | recipe_record · recipe_save · recipe_list · recipe_replay (deterministic replay, semantic anchors, strict/lenient escalation) |
| Evidence & safety | session_evidence · confirm_action |
Every mutation returns a receipt — page_fill reports landed_chars, while
type_ref fire-then-verifies async editors, so a silent page swap can't eat an
edit unnoticed. Sessions can also run headful ({"headful": true}) when
humans want to watch the agent work.
Every run records evidence. Each session writes an append-only event log
(events.jsonl), full page snapshots and the identity it used under
~/.ghostfox/recordings/ — fetch it any time with session_evidence.
Engine diagnostics. ghostfox-mcp --self-test walks the engine
pipeline (detection → spawn → juggler handshake → Browser.enable) and
prints a step-by-step report plus the engine's stderr tail on failure —
paste the output into an issue when a platform misbehaves.
E2E without emulators: Flutter web + any web app
Android E2E normally means emulators, Appium and a farm of devices.
Ghostfox takes the web route: build the Flutter app for the web
(flutter build web — same Dart codebase) and drive it with the
same senses used against hostile sites:
- Semantics tree, read natively — Flutter's a11y nodes (roles,
labels, bounds) land in
page_a11y(native=true)once semantics are enabled (one line in the app:SemanticsBinding.instance.ensureSemantics()). - Native clicks —
page_click_nativefires the Flutter buttons at their trusted a11y coordinates (verified: submit triggers, status renders). - Receipts +
page_diff+page_mutations+page_wait_stable— the same Act→Observe→Compare evidence loop, no polling guesswork. - Visual QA —
page_ui_auditjudges the rendered UI.
Honest scope: logic/flow/UI = fully covered; final visual parity with real devices (Impeller rendering) and platform channels (sensors, camera) still need a device or emulator pass.
Sponsor
Ghostfox is independent and self-funded. If it saves your team from captcha walls or vibe-code UI bugs, help keep the house open:
- GitHub Sponsors — monthly support, any amount
- Buy Me a Coffee — one-time
Companies: sponsorship + early access to the hosted Visual QA service
is open — sponsor the repo
or open an issue with the title sponsorship.
Or install in one command (Linux x86_64):
curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash
From source end-to-end (build the engine yourself):
see engine/README.md — make dir && make build.
Repository layout
runtime/ Rust: ghostfox-{core,fingerprint,mcp,eval} (MIT OR Apache-2.0)
engine/ Browser fork: patches, branding, build system (MPL-2.0)
AGENTS.md The agent playbook — how AI agents drive Ghostfox like a human
SKILL.md The compact agent skill — the golden loop + tool map at a glance
docs/JOURNEY.md The dev-log, todo list and the road ahead (the five senses)
Two directories, two licenses, one product. The runtime speaks Juggler natively — no Node, no Python at runtime.
Using Ghostfox with an AI agent (opencode, Codex, Cursor, Claude Code, ...)? Read
AGENTS.mdfirst — it's the distilled playbook from real agent runs: the READ → REASON → DECIDE → ACT loop, self-health (rate limits, drafts, notifications), rich-editor typing, and every known wall with its proven solution.
Why own the engine?
- Anti-detect that survives inspection. Spoofing happens inside the engine (navigator, screen, WebGL, fonts, WebRTC, timezone, audio) — not in injected JS that detectors can read.
- No cloud dependency. Your agent's identities and cookies never touch a third-party host.
- Upstream insurance.
engine/tracks daijro/camoufox asupstream; Ghostfox applies its own branding and can rebase whenever it wants — including if upstream patches go closed-source.
Status
v0.7 — alpha. Verified: identity coherence (500/500), full MCP round-trip
E2E (create → open → fill → submit), 8 captcha families E2E on production
sites (bilibili, hCaptcha-protected signups, TikTok), debug cortex
(console/errors/network), Docker image E2E (session → open → snapshot
inside a container), portable sessions across Camoufox-lineage browsers.
Distributed via PyPI, npm, Docker (GHCR) and the official MCP Registry.
Known limits are tracked in the changelogs under runtime/ and engine/.
Do not use against targets you don't have permission to test. This is a testing / research tool.
Credits
Ghostfox stands on the shoulders of giants — Camoufox (daijro) for the anti-detect patch stack, Mozilla Firefox for the engine, LibreWolf for the patch tooling lineage, and Playwright for the Juggler protocol.
License
engine/— MPL-2.0 (inherited from Firefox / Camoufox). See engine/LICENSE.runtime/— MIT OR Apache-2.0. See runtime/LICENSE-MIT.
Ghostfox MCP questions
How do I add Ghostfox MCP to Claude Code?
Run claude mcp add ghostfox -- uvx ghostfox in your terminal. Add --scope user to make it available in every project.
How do I add Ghostfox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Ghostfox prevent detection?
It uses engine-level anti-detect via C++ patches inside a custom Firefox fork, rather than relying on detectable injected JavaScript.
Can Ghostfox solve captchas?
Yes, it includes a native captcha suite that solves 8 families of captchas on-device using local models without needing paid cloud services.
Does it support mobile personas?
Yes, it can create Android personas with portrait screens, specific GPUs, and Android font stacks.
How can agents interact with the page?
Agents can act using stable references to elements via the accessibility tree, which avoids the need for CSS selectors.