Content
# Agentic Playwright MCP
Let AI Agents write Python scripts to control browsers with the MCP Server framework.
Based on Playwright, supports optional [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) anti-detection engine.
## Core Concept
**AI doesn't call tools one by one, but writes Python scripts.** The more you use, the smarter the system becomes.
```
User Intent → AI searches for skills → Reference examples generate scripts → Script engine executes → Browser operations
↳ If not hit → Check experience library → Generate temporary script → Sandbox execution → Save experience
↳ If failed → Self-healing mechanism → Visual fallback → Record new knowledge
```
## Three-Layer Evolution Architecture
```
Layer 3: Domains (Site Experience) ← domains/*.yaml + workspace/knowledge/
Layer 2: Skills (Muscle Memory) ← controls.py + skill_library/
Layer 1: Helpers (Primitives) ← actions.py: goto/click/fill/screenshot
```
| Layer | Responsibility | Evolution Method |
|------|------|---------|
| **Layer 1** | Atomic Operations | Unchanged |
| **Layer 2** | Control Functions | Extend new functions |
| **Layer 3** | Site Experience | Selector self-healing + Knowledge accumulation |
## Current Capabilities
| Scenario | Degree | Description |
|------|------|------|
| **Simple Tasks** (Search, Navigation, Screenshot) | ✅ Available | Directly runs through |
| **Medium Tasks** (Login, Fill Form, Page Turn) | ⚠️ Limited | Has templates, needs site adaptation |
| **Complex Tasks** (Multi-step, Cross-page) | ⚠️ Limited | Agent loop can run, inference ability is limited |
**Adapted Sites**: Baidu, Sogou, Dangdang, Bilibili, Toutiao, CSDN, Encyclopedia, Weather, Weibo, Jujin, IT Home, Coder Tutorial, Open China
## Quick Start
```bash
# Clone
git clone https://github.com/zceeeeee/agentic-playwright-mcp.git
cd agentic-playwright-mcp
# Install
pip install -e .
playwright install chromium
# Start GUI
browser-agent gui --port 8081
```
Open browser and visit **http://localhost:8081**
## Docker Deployment
```bash
# Clone
git clone https://github.com/zceeeeee/agentic-playwright-mcp.git
cd agentic-playwright-mcp
# Build image
docker compose build
# Start service (background running)
docker compose up -d
# View logs
docker compose logs -f
```
After service starts, MCP client can connect through `http://localhost:8000`
**Environment Variables**: Create `.env` file in project root directory to configure API Key:
```env
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here
```
**MCP Configuration (Claude Desktop)**:
```json
{
"mcpServers": {
"browser": {
"url": "http://localhost:8000/mcp"
}
}
}
```
**Stop Service**:
```bash
docker compose down
```
## Usage
### Web GUI
```bash
browser-agent gui --port 8081
```
### CLI
```bash
browser-agent setup # Initial configuration (interactive)
browser-agent serve # MCP service
browser-agent run "Help me search for Python tutorials on Baidu" # Single execution
browser-agent doctor # Check environment
browser-agent gui # Start Web GUI
```
### Python SDK
```python
from src.sdk import AgentLoop
with AgentLoop(headless=True) as agent:
result = agent.run("Help me search for Python tutorials on Baidu")
print(result.output)
```
### MCP (Claude Desktop)
```json
{
"mcpServers": {
"browser": {
"command": "browser-agent",
"args": ["serve"]
}
}
}
```
## Tool List
| Tool | Description |
|------|------|
| `run_task` | Natural language-driven autonomous Agent loop |
| `browse_skills` | Search skill library by keyword or URL |
| `get_skill` | Get skill source code and documentation |
| `run_script` | Execute Python script in restricted sandbox |
| `analyze_page` | Screenshot + Multi-modal LLM analyze page |
| `browser_launch` | Launch Chromium browser |
| `screenshot` | Take current page screenshot |
| `ping` | Health check |
## Script Engine Available Functions
```python
# Navigation
goto("https://example.com")
go_back()
# Element operations (support multiple alternative selectors)
click("#button", ".fallback-btn")
fill("#input", "hello")
# Domain configuration-driven (with self-healing)
smart_click("search_button", domain="baidu")
smart_fill("search_input", "Python tutorials", domain="baidu")
# Combined operations
smart_login("github", "user", "pass")
smart_search("baidu", "Python tutorials")
smart_fill_form("example", {"name": "Zhang San", "email": "test@test.com"})
# JavaScript execution
run_js('document.querySelector("#kw").value = "Python"')
# Waiting
wait_for_navigation(timeout=10)
wait_for_element("#result", timeout=10)
wait(2.0)
# Page information
url = get_url()
title = get_title()
text = get_text()
screenshot("page.png")
```
## Experience Evolution System
Reference Browser Harness's `agent-workspace` mode:
```
workspace/
├── scripts/ # Successful scripts (auto-save, auto-reuse)
├── selectors/ # Selector experience (success/failure records)
└── knowledge/ # Site knowledge (gotchas + patterns)
```
- **Script Reuse**: Automatically reuse saved script for same task second execution
- **Selector Experience**: Record each selector's success/failure times, sorted by reliability
- **Site Knowledge**: Record each site's special behaviors and precautions
## CloakBrowser Anti-detection Engine
```bash
pip install -e ".[stealth]"
USE_CLOAKBROWSER=true browser-agent gui
```
| Detection Service | Playwright | CloakBrowser |
|---------|-----------|-------------|
| reCAPTCHA v3 | 0.1 (bot) | **0.9** (human) |
| Cloudflare Turnstile | FAIL | **PASS** |
| FingerprintJS | DETECTED | **PASS** |
## Project Structure
```
agentic-playwright-mcp/
├── src/
│ ├── server.py # MCP entrance (8 tools)
│ ├── cli.py # CLI (serve/run/doctor/gui)
│ ├── sdk.py # Python SDK
│ ├── core/
│ │ ├── agent_loop.py # Agent loop engine
│ │ ├── script_engine.py # Script execution engine
│ │ ├── script_generator.py # Task intent parsing
│ │ ├── experience.py # Experience evolution system
│ │ ├── browser_manager.py # Dual-engine browser management
│ │ ├── event_bus.py # Event hook system
│ │ ├── recovery.py # Error recovery
│ │ └── vision.py # Visual module
│ ├── gui/app.py # Web GUI
│ ├── layer_1/actions.py # Atomic operations
│ ├── layer_2/controls.py # Advanced control functions
│ ├── layer_3/ # Domain configuration + Self-healing
│ └── skill_library/ # Standard script library
├── domains/ # Site selector configuration (19 sites)
├── workspace/ # Experience storage
├── tests/ # 570 tests
├── docs/ # MkDocs documentation
├── examples/ # Example scripts
└── Makefile
```
## Development
```bash
make dev # Install dependencies
make test # Run tests (570)
make lint # Code check
make format # Auto-fix
make docs # Start documentation server
```
## License
MIT
