Wraith MCP Server

Wraith gives an agent a stealth browser: Camoufox (a hardened Firefox) or a patched Chromium. The agent reads each page as a numbered list of controls and acts by number. Wraith runs as a CLI, a Python library, and an MCP server.

Some sites score reputation, not behavior. A new automated profile always scores as a bot there. Wraith does not try to fake that history. It borrows your own signed-in session from your real browser profile, so the site sees you.

What the agent sees

→ navigate("https://news.ycombinator.com/login")
URL: https://news.ycombinator.com/login
[0] @ (82,167)<a role=link href="forgot">Forgot your password?</a>
[1] @ (29,131)<input role=button type="submit" value="login">login</input>
[3] @ (175,60)<input role=textbox type="text" name="acct"/>
[4] @ (175,86)<input role=textbox type="password" name="pw"/>
…
→ type_text(3, "ada")
→ fill_secret(4, capability)    # a broker fills the password; the model never sees it
→ click(1)

Each line is one visible control that receives the pointer, with its point on the page. A modal hides the controls under it. After each action, Wraith reports what changed and the new text on the page.

Related MCP server: agent-browser

Why Wraith

🥷 Stealth engines Camoufox first, patched Chromium second. Both pass the rebrowser automation leak checks on macOS and Linux. The TLS and HTTP/2 fingerprint matches the browser in the User-Agent.

🪪 Borrowed identity Reuse your own signed-in session from Firefox, Zen, or Chrome. Reputation systems such as reCAPTCHA v3 see your history, not a new profile.

🤖 Made for agents Numbered snapshots, actions by number, change reports, frames, sliders, uploads, tabs, and a network log. read(find=…) returns only the passages you need.

🛡️ Guard rails Domain allowlist, page-text markers, opaque secret fills, an upload folder allowlist, and a watchdog that replaces a stuck browser.

⚡ No-browser fast path Clear a challenge once in the browser. Then replay the session over HTTP with the same TLS hello, through curl_cffi.

🔁 Profile sync Move a login for one domain from your laptop to a remote Wraith, through an end-to-end encrypted dead-drop. No account and no open port.

Measured results

The stealth benchmark runs every week on GitHub runners, headless. Run of 2026-10-17:

¹ The Linux runner has no GPU, so WebGL uses SwiftShader. ² Chrome 155 sends TLS extension 51764. curl_cffi cannot send it, so wraith fetch and the fetch tool add a note when they replay a session from another Chrome version.

Interactive challenges on public demo pages, with the agent aiming from a screenshot():

Vendors change their checks. These results are not a promise for your site.

Quickstart

1. Install

From source, with uv:

git clone https://github.com/YogevKr/wraith && cd wraith
uv sync
uv run camoufox fetch                             # the Camoufox build Wraith pairs with
uv run patchright install chromium               # optional: the Chromium engine

Or with pip:

pip install "wraith[fastpath] @ git+https://github.com/YogevKr/wraith"
camoufox fetch

2. Connect your MCP client

# Claude Code, from a clone
claude mcp add wraith -- uv run --directory /path/to/wraith wraith-mcp

# Claude Code, without a clone
claude mcp add wraith -- uvx --from git+https://github.com/YogevKr/wraith wraith-mcp

For Claude Desktop and other clients, see docs/AGENTS.md.

3. Ask

Open the English Wikipedia article on Tel Aviv and tell me the city's population.

With read(find="population"), the agent gets the passages that contain the term in one call, not the whole article.

Python library

from wraith import agent_browser

with agent_browser(engine="camoufox", headless=True) as ab:
    snap = ab.navigate("https://en.wikipedia.org/wiki/Tel_Aviv")
    print(snap.to_text())           # numbered controls
    print(ab.find("population"))    # passages that contain the term
    ab.click(12)                    # act on control [12]
    ab.type(3, "wraith", enter=True)
    print(ab.read())                # main content as markdown

Borrow your own signed-in session:

import wraith

with wraith.browser(engine="camoufox", geoip=True) as s:
    profile = wraith.find_zen_profiles()[0]      # or find_firefox_profiles()
    cookies = wraith.extract_cookies(profile, domain_filter="example.com")
    wraith.inject_cookies(s.context, cookies)
    s.page.goto("https://example.com")           # signed in as you

import wraith works when an optional browser dependency is missing. It leaves out the affected symbols and records why in wraith.missing_imports.

MCP tools

• navigate attempts HUMAN/PerimeterX Press & Hold challenges and closes cookie banners. It reports an error when verification fails.

• Snapshots show the chosen option of a <select>, the files of a file input, and the value of a range or color input. They list frames, and they end with Challenges: turnstile solved when a challenge token is present.

• read() returns the main content as markdown, in slices of 20,000 characters. read(find="population") returns only the passages with the term. read(full=True) includes the page chrome.

• Frames. Elements in visible iframes get indices like the main page and end with (frame N). For a frame with no readable elements, such as Turnstile, call click_frame(N, x, y). x and y are fractions of the frame's own size, also when the frame is rotated or tilted in 3D.

• drag(dx, dy, index=…) moves a slider knob along a human path: eased, with a small wobble, uneven timing, and a short overshoot on long drags.

• network_requests → network_response → fetch finds the JSON API that a page calls, then calls it without the browser.

• upload_file is off until you allow folders (see Configuration).

The full tool reference is in docs/AGENTS.md. Restart the MCP server after you upgrade Wraith.

Configuration

Provider credentials come from DATAIMPULSE_USERNAME / DATAIMPULSE_PASSWORD, ANYIP_USERNAME / ANYIP_PASSWORD, or --proxy-username-cmd and --proxy-password-cmd. Solver keys come from CAPSOLVER_API_KEY and TWOCAPTCHA_API_KEY. See docs/PLAYBOOK.md for proxy setup.

How Wraith gets through

There is no universal bypass. Wraith uses the lowest-cost method that works for each kind of defense.

flowchart LR
    page["Page with a bot defense"] --> kind{"Kind of defense"}
    kind -->|"JS challenge<br/>Reblaze ac_v2"| engine["Engine stealth<br/>Camoufox clears it"]
    kind -->|"Reputation score<br/>reCAPTCHA v3"| borrow["Borrowed identity<br/>your signed-in profile"]
    kind -->|"IP rate limit<br/>Reblaze 474 / 481"| proxy["New residential exit<br/>ProxyPool"]
    kind -->|"Widget<br/>Press & Hold, Turnstile, slider"| human["Human input<br/>hold, click_frame, drag"]
    kind -->|"Hard block<br/>HTTP 492"| stop["Stop with a clear error"]

1. Engine stealth. Firefox skips the Chrome-only detection checks, so most fingerprint tells never run. This alone clears solvable JS interstitials such as Reblaze/Link11 ac_v2. clear_challenge() navigates and waits for the clearance cookie. It needs no cookies and no proxy.

2. Identity borrowing. reCAPTCHA v3 has no client-side solver. It returns a score from your Google cookies, browsing history, and IP reputation. A new profile scores about 0.1–0.3. Wraith injects your own warmed session from disk (extract_cookies → inject_cookies), or captures a live bearer token (SessionHarvester).

3. Residential exit rotation. Cookies and waiting do not clear an IP rate limit. ProxyPool and the DataImpulse and anyIP providers feed new exits into launch(proxy=…) and clear_challenge(proxy_pool=…).

4. Human input. navigate holds a HUMAN Press & Hold button by itself. For Turnstile and sliders, the agent aims from a screenshot. Wraith moves, clicks, and drags with human timing.

5. Not solvable. Hard blocks, and reCAPTCHA v3 with no warmed identity, raise an error with the reason. Wraith does not pretend.

docs/DETECTION.md lists how to identify each vendor. docs/PLAYBOOK.md gives the decision steps.

Sessions: borrow, sync, hand off

sequenceDiagram
    participant L as Laptop
    participant R as Relay (Cloudflare Worker)
    participant W as Remote Wraith
    L->>L: read your login, keep one domain
    L->>R: sealed blob (ChaCha20-Poly1305) in a random slot
    L-->>W: one-time pairing code, out of band
    W->>R: pull once, the slot burns
    W->>W: open in memory, inject, browse as you

• Borrow (wraith borrow, MCP borrow) reads cookies from your Firefox or Zen profile and injects them. Chrome needs the explicit wraith profile sync --from chrome path, which uses the OS keychain.

• Profile sync (wraith profile sync → receive_profile) moves a domain-scoped login to a headless box or a cloud VM. The relay sees only ciphertext.

• Hand off (save_state(path, for_chromium=True)) exports a session for agent-browser.

• Fast path (wraith fetch, MCP fetch) replays a captured session without a browser.

Details and limits: docs/SESSIONS.md.

Safety

claude mcp add wraith -e WRAITH_ALLOWED_DOMAINS="example.com,*.example.com" \
  -- uv run --directory /path/to/wraith wraith-mcp

example.com matches only that host. *.example.com also matches every subdomain. List every host that the site needs, such as CDNs and challenges.cloudflare.com. SECURITY.md gives the limits of each control.

CLI

The default engine is camoufox. Use --engine chromium for patched Chromium, or --engine auto to let Wraith choose.

One browser across commands

Each one-shot command above starts and closes its own browser. To drive one page step by step from a shell or a script, use wraith call. It runs any MCP tool, with the same arguments, in a background session that keeps one browser open:

wraith call borrow example.com             # starts the session on first use
wraith call navigate https://example.com/account
wraith call click 12
wraith call type_text 4 "hello" --enter
wraith call read --find invoice
wraith call screenshot --out page.png
wraith session stop                        # or it stops after 30 min idle

wraith call lists the tools, and wraith call TOOL --help shows a tool's arguments. A session uses the MCP server's defaults (--engine auto, headless). For a different engine, a proxy, or a domain allowlist, run wraith session start --engine chromium --allowed-domains example.com first. Use --session NAME to keep several sessions apart. Only your user can connect to a session.

uv run wraith agent https://example.com --json
uv run wraith borrow https://example.com --host example.com
uv run wraith harvest https://example.com --target api.example.com --cookie session -o example.session.json
uv run wraith fetch https://api.example.com/me --session example.session.json --show-body
uv run wraith selftest --json
uv run wraith benchmark run --engine chromium --out results/chromium.json
uv run wraith benchmark compare results --previous last-week --summary summary.md
uv run wraith score --engine chromium --json
uv run wraith detect https://example.com --json
uv run wraith launch https://example.com --headless --no-wait
uv run wraith profile sync --relay https://<name>.workers.dev --from chrome --domain elal.com
uv run wraith profile receive <pairing-code> --open https://www.elal.com/
uv run wraith profile revoke <pairing-code>

Architecture

flowchart TB
    mcp["MCP server"] --> agent["agent<br/>AgentBrowser"]
    cli["CLI"] --> agent
    cli -->|wraith call| daemon["daemon<br/>background session"]
    daemon --> mcp
    agent --> snapshot["snapshot"]
    agent --> behavior["behavior"]
    agent --> engine["engine"]
    engine --> camoufox[("Camoufox")]
    engine --> chromium[("patchright Chromium")]
    engine --> proxy["proxy · providers"]
    identity["identity · chrome"] --> engine
    profile["profile · deaddrop"] --> identity
    harvest["harvest"] --> fastpath["fastpath<br/>curl_cffi"]

Examples: examples/ has borrow_session.py, score_check.py, and detect_waap.py.

Wraith pins playwright == 1.62.x and Camoufox 0.5.9b5. Camoufox 0.4.x crashed on playwright >= 1.60 (a Firefox pageError serialization bug); 0.5.6 fixed it with a browser/playwright floor table. Wraith still refuses a Playwright above the package's tested range and gives an error with the fix. patchright has its own version and is not affected.

Wraith also pairs the Camoufox browser with the build its package ships with (158.0-beta.40), because a browser and Playwright from different releases speak different versions of the automation protocol. camoufox fetch installs the paired build. Wraith selects that build even when newer releases exist. If it is missing, launch fails with the install command; it does not fetch a new beta.

The Chromium engine uses an installed Google Chrome when it finds one, because the bundled Chrome for Testing build is a known bot signal. Pass channel="chromium" to launch() to use the bundled build.

Docs

Responsible Use & Legal

Wraith is a dual-use tool. Like the other projects in its category (Camoufox, nodriver, browser-use, undetected-chromedriver), it can be used well or badly. It is published for legitimate purposes:

• Access to your own accounts and data, on your own machine, with your own warmed browser profile.

• Authorized security testing and bot-defense research, where you have permission to test the target.

• Personal automation, collection of data that you are entitled to, and reproducible research into anti-bot and WAAP systems.

Rules:

• Respect the Terms of Service of each site and all applicable laws (for example, the CFAA and its equivalents).

• Identity borrowing reads only your own local browser profiles. Do not use it on accounts or sessions that are not yours.

• Do not use Wraith for fraud, account takeover, credential stuffing, mass abuse, spam, or to get around access controls that you are not authorized to bypass.

You are responsible for how you use this software. If your use is not clearly one of the legitimate cases above, do not do it. Wraith is released under the MIT License with no warranty.

Tests

uv run pytest -q

The offline suite needs no browser binaries and no network. WRAITH_LIVE_TEST=1 uv run pytest tests/test_live_*.py launches real browsers against pages on 127.0.0.1 only. The macOS CI job runs them on each push. The weekly stealth benchmark uses public detector pages (bot-detector.rebrowser.net, tls.peet.ws).

Contributing

Read CONTRIBUTING.md for setup, the module layout, and pull-request norms. In short: branch from main, run uv sync --extra dev, keep uv run pytest -q green, and run uv run ruff check . before you open a PR.

License

MIT. See LICENSE.