wraith-mcp

AI-native stealth browser MCP server. Tell it what to do — it figures out how.

Browser Use (AI vision navigation) + Patchright (bot detection bypass).

Why This One?

One command does it all — no selectors, no step-by-step scripting:

"Log into my dashboard and download the monthly report"

Quick Start

Add wraith-mcp as MCP server

Install

pip install wraith-mcp

Setup

Add to your MCP config (.mcp.json, .cursor/mcp.json, .windsurf/mcp.json, etc.):

{
  "mcpServers": {
    "wraith": {
      "command": "wraith-mcp"
    }
  }
}

Works with any MCP client: Cursor, Windsurf, VS Code, Cline, Roo Code, OpenCode, Codex, and more.

The browser window is visible by default. Set "HEADLESS": "true" in env to run it headless — recommended for servers, CI, and Docker (the Docker image already sets it).

These clients call Wraith over MCP. The low-level tools work with no API key — your client's AI drives them directly. The autonomous browse/extract tools use MCP sampling when supported, otherwise a fallback key (see below).

Do I Need an API Key?

No — for the low-level tools. navigate, snapshot, click, type_text, scroll, press_key, get_content, screenshot, pdf, and tabs need no API key: your MCP client's model (Claude Code, Codex, OpenCode, …) calls them directly and is the brain, exactly like playwright-mcp.

Only the autonomous Agent tools — browse and extract, which plan the steps themselves — need a model. They use MCP sampling when the client supports it, otherwise a fallback provider key. Note that many clients, including Claude Code today, do not implement MCP sampling, so browse/extract need a fallback key there (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, or Ollama via OLLAMA_MODEL). The low-level tools work either way.

Tools

Keyless — your client's AI drives the browser directly, no API key:

Autonomous AI Agent — needs MCP sampling or a fallback key:

The low-level tools share a persistent browser via session_id (default "default"): call navigate once, then snapshot/click/type_text/… reuse the same page. browse/extract also accept session_id.

Fallback LLM Providers

Use these only when your MCP client does not support sampling, or when you want to force Wraith to use an explicit provider.

Set BROWSER_USE_MODEL to override the default model or provide a sampling model hint to the MCP client.

Browser Options

Wraith keeps its default browser profile unless optional env vars are set. It can forward Browser Use profile knobs for domain policy (BROWSER_ALLOWED_DOMAINS, BROWSER_PROHIBITED_DOMAINS, BROWSER_BLOCK_IP_ADDRESSES=true for Browser Use's direct-IP navigation block), session/artifacts (BROWSER_STORAGE_STATE, BROWSER_USER_DATA_DIR, BROWSER_DOWNLOADS_PATH, BROWSER_RECORD_HAR_PATH, BROWSER_RECORD_VIDEO_DIR, BROWSER_TRACES_DIR), and permissions, viewport, or wait timing (BROWSER_PERMISSIONS, BROWSER_VIEWPORT, BROWSER_MINIMUM_WAIT_PAGE_LOAD_TIME, BROWSER_WAIT_FOR_NETWORK_IDLE_PAGE_LOAD_TIME, BROWSER_WAIT_BETWEEN_ACTIONS) when the installed Browser Use BrowserProfile supports those fields. Domain/IP policy env vars fail closed on unsupported Browser Use versions.

Locale & timezone (stealth): by default Wraith pins neither — it inherits the host locale and timezone so they stay consistent with your exit IP. Forcing en-US on a non-US IP is itself a bot signal, so set these only when routing through a proxy: point BROWSER_LOCALE and BROWSER_TIMEZONE at the proxy's region (e.g. en-US + America/New_York) so locale, timezone, and IP agree. BROWSER_TIMEZONE is applied via CDP (Emulation.setTimezoneOverride) because Browser Use's BrowserProfile has no timezone field.

Downloads: files save to ./downloads (relative to the server's working directory) by default so they persist — Browser Use otherwise uses a temp dir that gets cleaned up on session stop, losing the file. Override with BROWSER_DOWNLOADS_PATH, and use the list_downloads tool to retrieve the saved paths after a click/navigate triggers a download.

Docker

docker build -t wraith-mcp .
docker run -i --rm wraith-mcp

SSE mode for local-only testing:

docker run -p 127.0.0.1:8808:8808 wraith-mcp --transport sse --host 0.0.0.0 --port 8808

Do not expose the SSE port directly to an untrusted network. If you need remote access, put it behind an authenticated proxy or SSH tunnel and restrict browsing with BROWSER_ALLOWED_DOMAINS plus BROWSER_BLOCK_IP_ADDRESSES=true.

SSE Transport

wraith-mcp --transport sse --host 127.0.0.1 --port 8808

The SSE host defaults to 127.0.0.1. Binding to 0.0.0.0 is only appropriate behind an authenticated proxy or another trusted network boundary.

How It Works

Keyless (low-level tools) — your MCP client's AI is the brain:

Client AI -> MCP Server -> Patchright Chromium

1. navigate opens a page and returns its interactive elements

2. The client AI reads the [index] <tag> text snapshot and decides what to do

3. It calls click/type_text/scroll/… by index — no model runs in Wraith

4. Patchright executes without triggering bot detection

Autonomous (browse/extract) — Wraith drives a Browser Use Agent:

AI Agent -> MCP Server -> Browser Use Agent -> Patchright Chromium

1. Describe a task in natural language

2. Browser Use asks the MCP client model through sampling, or a fallback provider

3. Browser Use sees the page (screenshot + DOM) and decides actions

4. Patchright executes without triggering bot detection

Security

• URL scheme validation (http/https only)

• max_steps capped at 50 server-side

• Input length capped at 4000 chars

• Task timeout (default 120s, configurable via BROWSER_TASK_TIMEOUT)

• Proxy support via PROXY_SERVER

• SSE transport binds to 127.0.0.1 by default; do not expose it directly without authentication

• Browser Use page context is sent to the MCP client model via sampling, or to the configured fallback provider

Limitations

• Binary-level stealth only (no Runtime.enable CDP fix)

• Enterprise WAFs may still block without residential proxies

• Fresh browser per call (~3s startup)

• The low-level tools (navigate/snapshot/click/…) are keyless — no model needed

• browse/extract need MCP sampling or a fallback key; many clients (incl. Claude Code) don't implement sampling, so a fallback key is required there

License

MIT