mithwire-mcp 0.5.1

🤖 Build, test, and debug web automations with AI agents.
An MCP server that gives LLM agents direct control over stealth Chromium browsers.
Dual Engine (CDP + CloakBrowser) • Live Debugging • Proxy Alignment • Persistent Profiles

💡 What is Mithwire MCP?

mithwire is a production-ready anti-detect browser engine. Mithwire MCP is the Model Context Protocol server that exposes Mithwire's stealth browser capabilities directly to AI models like Claude, Cursor, and autonomous agents.

Instead of manually writing fragile browser-automation glue code, you can hand over the MCP server to an AI agent to build, execute, test, and debug web automations autonomously.

Your AI agent can invoke structured MCP tools (session_start, browser_navigate, browser_click, browser_snapshot, browser_solve_cloudflare) to explore pages, handle logins and captchas, capture console and network logs, and inspect DOM state in real time.

🛠️ Built for Developing & Debugging Automations

Mithwire MCP was designed specifically as an interactive development harness for AI agents and human developers:

• 🤖 Autonomous Automation Authoring: Give your AI agent a high-level prompt ("Build a script that logs into service X and downloads report Y"). The agent uses MCP tools to navigate, find selectors, verify state, and iterate until the script works.
• 🔍 Live Inspection & Diagnostics: Agents can capture DOM snapshots, monitor JavaScript console errors, record full CDP network traces, and read storage/cookies at any point during execution.
• 🖥️ Visual VNC Debugging: Pre-packaged with an embedded noVNC web viewer (http://localhost:6080/vnc.html). Watch your AI agent interact with the browser live in your desktop browser.
• 🧪 E2E Test Prototyping: Rapidly prototype and debug resilient scrapers and workflows without getting blocked by anti-bot protections.

💥 The Problem for AI Agents

When AI agents attempt web operations using traditional tools (Playwright, Puppeteer, Selenium, or standard web fetchers), they immediately hit anti-bot walls:

• ❌ Instant Anti-Bot Blocks: Standard automation frameworks leak navigator.webdriver = true and ChromeDriver artifacts, triggering Cloudflare, Akamai, and DataDome challenges.
• ❌ Proxy & IP Mismatches: Agents using proxies often leak their host IP via STUN/WebRTC or present timezone/locale settings that contradict their proxy exit location.
• ❌ State Loss Across Turns: AI agents frequently lose cookies, session state, or local storage between execution turns or subagent invocations.

🛡️ The Mithwire MCP Solution

Mithwire MCP solves these challenges natively for AI agent workflows:

1. 🥷 Stealth by Design: Operates on Mithwire—no WebDriver, no Selenium, zero navigator.webdriver leaks, with built-in Cloudflare Turnstile bypass.
2. ⚡ Dual Stealth Engines: Support for both lightweight cdp mode (standard Chrome) and C++-patched stealth mode (CloakBrowser) per session.
3. 🌍 Automatic Proxy & Egress Alignment: Auto-probes proxy health before launching Chromium and aligns timezone, locale, languages, and geolocation to match the proxy exit IP.
4. 👤 Persistent Profiles & State Store: Reusable browser profiles (profiles/) store cookies, localStorage, proxies, and persisted fingerprints across agent runs.
5. 🔒 WebRTC Leak Protection: Automatically guards STUN/UDP queries against leaking the host's real IP address.

⚡ Engine Modes & Capabilities

Configure stealth levels on a per-session or per-profile basis:

✨ Key Features & Capabilities

• 🤖 Complete Agent Toolset: Full toolsuite covering navigation, DOM querying, clicking, typing, scrolling, screenshots, network capture, and JS evaluation.
• 🧩 Cloudflare Bypass: Solves Cloudflare Turnstile challenges on command via browser_solve_cloudflare.
• 🗂️ Centralized State Store: Default ~/.mithwire-mcp directory manages persistent profiles, proxy registries, and cookie import/export files.
• 🛰️ Proxy Registry & Alignment: Store proxy credentials once and reference them by name. Automatically validates proxy health and aligns timezone/locale/geo before Chromium launches.
• 🐳 Docker-Ready with Visual Debugging: Pre-configured Docker container with Xvfb, CloakBrowser, and noVNC web viewer (http://localhost:6080/vnc.html).

🚀 Installation

# Standard install (CDP mode)
pip install mithwire-mcp

# With Stealth Mode support (CloakBrowser)
pip install "mithwire-mcp[stealth]"

💻 MCP Client Configuration

Add Mithwire MCP to your MCP client config (e.g. Cursor, Claude Desktop):

{
  "mcpServers": {
    "mithwire-mcp": {
      "command": "mithwire-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

🐳 Running in Docker (With Visual VNC Debugging)

For isolated execution or local visual observation:

# Pull public Docker image
docker pull ghcr.io/codeisalifestyle/mithwire-mcp:latest

# Run local dev container with noVNC enabled
docker compose -f docker-compose.dev.yml up -d --build

Endpoints:

• 🔌 MCP Server (Streamable HTTP): http://localhost:7867
• 🖥️ noVNC Visual Viewer: http://localhost:6080/vnc.html

🧰 Available MCP Tools Reference

🧹 No Orphaned Chrome

Every session owns the Chrome process it launched, and the server makes sure none outlives it:

• A session_start that fails, times out or is cancelled by the client tears down its half-started browser (no more empty windows left behind).
• session_stop, session_stop_all and server shutdown close browsers concurrently and delete their temporary profiles.
• On SIGTERM/SIGHUP/SIGINT the server stops every browser immediately and exits instead of hanging.
• If the server itself is killed outright (SIGKILL, OOM, a crash), a tiny watchdog process from the engine terminates exactly its browsers and removes their temporary profiles. Set MITHWIRE_NO_EXIT_GUARD=1 to disable it.

scripts/smoke_process_lifecycle.py checks all of this against a real stdio server and a real Chrome (it also runs in CI).

📜 License

Distributed under the MIT License. Powered by mithwire (AGPL-3.0).