Metadata-Version: 2.4
Name: wraith-mcp
Version: 0.2.1
Summary: AI-native stealth browser MCP server — Browser Use + Patchright
Project-URL: Repository, https://github.com/Koreahwan/wraith-mcp
Author: KH
License: MIT
License-File: LICENSE
Keywords: ai-agent,browser-automation,browser-use,cline,codex,cursor,mcp,opencode,patchright,stealth,windsurf,wraith
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: browser-use>=0.12.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-google-genai>=2.0.0
Requires-Dist: langchain-ollama>=0.3.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: patchright>=1.49.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# wraith-mcp

[![PyPI](https://img.shields.io/pypi/v/wraith-mcp)](https://pypi.org/project/wraith-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

[Browser Use](https://github.com/browser-use/browser-use) (AI vision navigation) + [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (bot detection bypass).

## Why This One?

| | wraith-mcp | playwright-mcp | stealth-browser-mcp | browser-use-mcp-server |
|---|---|---|---|---|
| Navigation | **AI vision** (self-healing) | CSS selectors | CSS selectors | AI vision |
| Bot detection bypass | **Patchright** (binary-level) | None | nodriver | None |
| Tools | 2 (`browse`, `extract`) | 20+ | 90+ | via Agent |
| Site layout changes | **Adapts automatically** | Breaks | Breaks | Adapts |
| LLM providers | **6** (Anthropic, OpenAI, OpenRouter, Google, Ollama, +compatible) | N/A | 1 | 1 |

**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

```bash
pip install wraith-mcp
```

## Setup

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

```json
{
  "mcpServers": {
    "wraith": {
      "command": "wraith-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-key",
        "HEADLESS": "true"
      }
    }
  }
}
```

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

## Tools

| Tool | Description |
|------|-------------|
| `browse` | Execute any browser task in natural language |
| `extract` | Pull structured data from a page |
| `screenshot` | Capture a page as base64 PNG |
| `close_session` | Close a persistent browser session |

All tools support `session_id` for persistent sessions across multiple calls.

## LLM Providers

| Provider | Key |
|----------|-----|
| Anthropic (default) | `ANTHROPIC_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| DeepSeek / Groq / Together | `OPENAI_API_KEY` + `OPENAI_BASE_URL` |
| Google Gemini | `GOOGLE_API_KEY` |
| Ollama (local) | `OLLAMA_MODEL` |

All providers included. Set `BROWSER_USE_MODEL` to override the default model.

## Docker

```bash
docker build -t wraith-mcp .
docker run -i --rm -e ANTHROPIC_API_KEY=your-key wraith-mcp
```

SSE mode (remote/cloud):

```bash
docker run -p 8808:8808 -e ANTHROPIC_API_KEY=your-key wraith-mcp
```

## SSE Transport

```bash
wraith-mcp --transport sse --port 8808
```

## How It Works

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

1. Describe a task in natural language
2. Browser Use sees the page (screenshot + DOM) and decides actions
3. 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`

## Limitations

- Binary-level stealth only (no `Runtime.enable` CDP fix)
- Enterprise WAFs may still block without residential proxies
- Fresh browser per call (~3s startup)
- Requires an LLM API key

## License

MIT
