<p align="center">
  <img src="assets/mithwire-mcp-banner.jpg" alt="mithwire-mcp" width="760">
</p>

<p align="center">
  <b>🤖 Build, test, and debug web automations with AI agents.</b><br>
  An MCP server that gives LLM agents direct control over driverless Chromium browsers.<br>
  <b>Dual Engine (CDP + CloakBrowser) • Live Debugging • Proxy Alignment • Persistent Profiles</b>
</p>

<p align="center">
  <a href="https://pypi.org/project/mithwire-mcp/"><img src="https://img.shields.io/pypi/v/mithwire-mcp?style=for-the-badge&color=d62839&label=pip%20install%20mithwire-mcp" alt="PyPI"></a>
  <a href="https://pypi.org/project/mithwire-mcp/"><img src="https://img.shields.io/pypi/pyversions/mithwire-mcp?style=for-the-badge&color=3776ab&logo=python&logoColor=white" alt="Python versions"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-6b4fbb?style=for-the-badge" alt="MCP"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2ea44f?style=for-the-badge" alt="License"></a>
  <a href="https://github.com/elendil-tech/mithwire"><img src="https://img.shields.io/badge/⚙️_engine-mithwire-111111?style=for-the-badge" alt="mithwire engine"></a>
</p>

---

## 💡 What is Mithwire MCP?

[`mithwire`](https://github.com/elendil-tech/mithwire) is a driverless CDP browser automation engine for Python. **Mithwire MCP** is the Model Context Protocol server that exposes Mithwire's browser control, DOM inspection, and environment-emulation capabilities directly to AI clients such as **Claude, Cursor, and autonomous coding agents**.

Instead of manually writing fragile browser-automation glue code, you can **connect the MCP server to an AI agent** to build, execute, test, and debug web workflows interactively.

Your AI agent can invoke structured MCP tools (`session_start`, `browser_navigate`, `browser_click`, `browser_snapshot`, `browser_network_requests`) to explore pages, verify UI flows, capture console and network logs, and inspect DOM state in real time.

---

## 🛠️ Built for Developing & Debugging Automations

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

- 🤖 **Autonomous Workflow Authoring:** Give your AI agent a high-level goal ("Verify the checkout flow and capture any network errors"). The agent uses MCP tools to navigate, inspect selectors, verify state, and iterate until the test passes.
- 🔍 **Live Inspection & Diagnostics:** Agents can capture interactive DOM snapshots, monitor JavaScript console errors, record full CDP network traces, and inspect 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 & Localization Testing:** Prototype and debug end-to-end browser tests across timezones, locales, and proxy egress locations.

---

## 💥 Why Driverless CDP Matters for AI Agents

When AI agents run browser workflows using legacy WebDriver stacks or stateless fetchers, several common failure modes arise:

- ❌ **WebDriver Artifacts & Drift:** Standard WebDriver binaries inject `navigator.webdriver = true` and driver globals, and document-level JS shims fail to propagate to Web Workers and HTTP Client Hints.
- ❌ **Proxy & Locale Mismatches:** Testing through regional proxies without aligning timezone, locale, and WebRTC settings causes inconsistent localization state.
- ❌ **State Loss Across Turns:** AI agents frequently lose cookies, session state, or local storage between execution turns or subagent invocations.

---

## 🛡️ The Mithwire MCP Architecture

Mithwire MCP addresses these challenges natively for AI agent workflows:

1. ⚡ **Driverless CDP Engine:** Built on Mithwire—speaks raw Chrome DevTools Protocol with no WebDriver or Selenium dependency.
2. 🔧 **Dual Engine Modes:** Support for both standard `cdp` mode (stock Chrome/Chromium) and source-patched `stealth` mode ([CloakBrowser](https://github.com/CloakHQ/CloakBrowser)) for cross-OS environment emulation.
3. 🌍 **Automatic Proxy & Egress Alignment:** Validates proxy connectivity before launching Chromium and optionally aligns timezone, locale, languages, and geolocation to match the proxy region.
4. 👤 **Persistent Profiles & State Store:** Reusable browser profiles (`profiles/`) store cookies, localStorage, proxy bindings, and environment configurations across agent runs.
5. 🔒 **WebRTC Leak Protection:** Configurable STUN/UDP candidate filtering to prevent host interface leaks during proxied testing.

---

## ⚡ Engine Modes & Capabilities

Configure execution engines on a per-session or per-profile basis:

| Engine Mode | Binary | Capabilities | Best Suited For |
| :--- | :--- | :--- | :--- |
| **`cdp`** (Default) | Stock Chrome / Chromium | Fast, reliable CDP `Emulation` overrides for timezone, locale, geo, UA, platform, and device metrics. | Local workstations, remote Linux servers, E2E testing, fast script prototyping. |
| **`stealth`** | [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) | C++ source-level configuration for Canvas, WebGL GPU strings, AudioContext, native fonts, and viewport geometry. | Cross-OS environment emulation on Linux servers and browser-fingerprint consistency research. |

---

## ✨ Key Features & Capabilities

- 🤖 **Complete Agent Toolset:** Full toolsuite covering navigation, DOM querying, clicking, typing, scrolling, screenshots, network capture, and JS evaluation.
- 🗂️ **Centralized State Store:** Default `~/.mithwire-mcp` directory manages persistent profiles, proxy registries, and cookie import/export files.
- 🛰️ **Proxy Registry & Alignment:** Store proxy configurations once and reference them by name, with optional pre-flight connectivity and locale alignment.
- 🐳 **Docker-Ready with Visual Debugging:** Pre-configured Docker container with Xvfb, Chromium, and noVNC web viewer (`http://localhost:6080/vnc.html`).

---

## 🚀 Installation

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

# With source-patched Chromium support (CloakBrowser)
pip install "mithwire-mcp[stealth]"
```

---

## 💻 MCP Client Configuration

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

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

---

## 🐳 Running in Docker (With Visual VNC Debugging)

For isolated execution or local visual observation:

```bash
# Pull public Docker image
docker pull ghcr.io/elendil-tech/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

<details>
<summary><b>🔁 Session Lifecycle</b></summary>

- `session_start` - Launch a new browser session (ephemeral or persistent profile)
- `session_list` - List active browser sessions
- `session_get` - Get session status and identity metadata
- `session_set_fingerprint` - Override the active session environment fingerprint
- `session_rotate_proxy` - Rotate the proxy exit IP and optionally re-align locale/timezone
- `session_state_paths` - Show state directory layout (profiles, proxies, cookies)
- `session_set_policy` / `session_get_policy` - Set or read per-session security policy
- `session_set_download_dir` - Change the session download directory
- `session_warmup` - Visit initial pages to initialize session state
- `session_stop` - Close a specific session
- `session_stop_all` - Terminate all running sessions
</details>

<details>
<summary><b>👤 Profile & Proxy Management</b></summary>

- `session_profile_list` / `session_profile_get` / `session_profile_set` / `session_profile_delete` - CRUD for persistent profiles
- `session_profile_regenerate_fingerprint` - Regenerate a profile's fingerprint via BrowserForge
- `session_proxy_list` / `session_proxy_get` / `session_proxy_set` / `session_proxy_delete` - Proxy registry CRUD
</details>

<details>
<summary><b>🎮 Browser Navigation & DOM Actions</b></summary>

- `browser_url` - Get the current page URL
- `browser_navigate` / `browser_back` / `browser_forward` / `browser_reload` - Navigation
- `browser_snapshot` - Take interactive DOM snapshot with element references
- `browser_query` - Find elements by CSS selector or text
- `browser_click` / `browser_mouse_click` / `browser_mouse_move` / `browser_press_hold` / `browser_type` - User interactions
- `browser_scroll` - Scroll the page or an element
- `browser_handle_dialog` - Accept or dismiss browser dialogs
- `browser_set_file_input` - Set files on a file input element
- `browser_take_screenshot` - Capture page screenshot
</details>

<details>
<summary><b>🗂️ Tabs</b></summary>

- `browser_tab_list` / `browser_tab_current` - List open tabs or get the active tab
- `browser_tab_new` / `browser_tab_switch` / `browser_tab_close` - Create, switch, or close tabs
</details>

<details>
<summary><b>⏳ Waits</b></summary>

- `browser_wait` - Wait for a fixed duration
- `browser_wait_for_selector` - Wait until a CSS selector appears
- `browser_wait_for_text` - Wait until text appears on the page
- `browser_wait_for_url` - Wait until the URL matches a pattern
- `browser_wait_for_function` - Wait until a JS expression returns truthy
- `browser_wait_for_network_idle` - Wait until network activity settles
</details>

<details>
<summary><b>📡 Cookies, Storage & Network</b></summary>

- `browser_cookies_get` / `browser_cookies_set` / `browser_cookies_save` / `browser_cookies_clear`
- `browser_storage_get` / `browser_storage_set` / `browser_storage_clear`
- `browser_console_messages` - Read captured console log messages
- `browser_network_requests` - List captured network requests
- `browser_network_capture_start` / `browser_network_capture_get` / `browser_network_capture_stop` / `browser_network_capture_status`
- `browser_downloads` - List downloaded files
</details>

<details>
<summary><b>🔧 Advanced: HTML, JS Evaluation & Tracing</b></summary>

- `browser_html` - Get the raw HTML of the current page or an element
- `browser_evaluate` - Execute arbitrary JavaScript in the page context
- `session_trace_start` / `session_trace_stop` / `session_trace_get` - Record and inspect CDP traces
- `session_trace_export` / `session_trace_replay` - Export or replay recorded traces
</details>

---

## 🧹 Deterministic Process Lifecycle (No Orphaned Chrome)

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

- A `session_start` that fails, times out, or is cancelled by the client tears down its half-started browser.
- `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 cleanly.
- If the server itself is killed outright (`SIGKILL`, OOM, a crash), a lightweight watchdog process from the engine terminates its launched browsers and removes their temporary profiles. Set `MITHWIRE_NO_EXIT_GUARD=1` to disable it.

`scripts/smoke_process_lifecycle.py` verifies all of these guarantees against a real stdio server and a local Chrome instance in CI.

---

## ⚖️ Dual-Use & Responsible Use Notice

Mithwire MCP is a dual-use browser automation and debugging bridge intended for **interactive software testing, QA validation, browser-fingerprint research, and authorized AI agent workflows**.

- **Authorized Use Only:** Users are responsible for complying with applicable laws and the Terms of Service of any websites or systems accessed through this MCP server.
- **No Unlawful Circumvention or Abuse:** This software must not be used for unauthorized access, credential stuffing, spam, coordinated inauthentic activity, or disrupting third-party services.
- **Security & Abuse Contact:** To report a security vulnerability or a third-party abuse inquiry, please see [SECURITY.md](SECURITY.md).

---

## 📜 License

Distributed under the **MIT License**. Powered by [**mithwire**](https://github.com/elendil-tech/mithwire) (AGPL-3.0).