# Arche Browser
MCP Server for Browser Automation and Full Local PC Control.
Control a real Chrome browser AND your entire computer from Claude Code or any MCP client.
## Features
- **Full Browser Control**: Navigation, clicks, typing, screenshots, and more
- **Full PC Control**: Shell commands, Python execution, file system, clipboard, processes
- **Real Browser**: Uses your actual Chrome with cookies, extensions, login sessions
- **Remote Access**: Control browser/PC on any machine via SSE transport
- **Token Authentication**: Secure remote access with auto-generated tokens
- **Minimal Design**: Just a few powerful primitives that can do anything
## Design Philosophy
Inspired by Eric Gamma's principles: **Simple, Flexible, Powerful**
Instead of hundreds of specific tools, Arche provides a few powerful primitives:
| Primitive | What it does | What you can achieve |
|-----------|--------------|----------------------|
| `shell()` | Execute any shell command | Volume, reboot, programs, services, ANYTHING |
| `python_exec()` | Execute Python code | Camera, Excel, AI, complex logic, ANYTHING |
| `screen_capture()` | Desktop screenshot | Visual feedback for AI |
With just `shell` and `python_exec`, AI can literally control **EVERYTHING** on your computer.
## Installation
```bash
# From PyPI
pip install arche-browser
# From GitHub
pip install git+https://github.com/GizAI/arche-browser.git
# One-liner (no install)
uvx arche-browser
```
## Usage
### Browser Only (Default)
```bash
arche-browser
```
Claude Code config:
```json
{"mcpServers": {"browser": {"command": "arche-browser"}}}
```
### Full PC Control
```bash
arche-browser --local
```
Claude Code config:
```json
{"mcpServers": {"arche": {"command": "arche-browser", "args": ["--local"]}}}
```
### PC Control Only (No Browser)
```bash
arche-browser --local --no-browser
```
### Remote Access (SSE)
On the machine with Chrome:
```bash
arche-browser --sse --port 8080 --local
# Output:
# [*] Auth: ENABLED
# [*] Token: abc123...
# [*] Connect URL: http://localhost:8080/sse?token=abc123...
```
On Claude Code:
```json
{"mcpServers": {"remote": {"url": "http://YOUR_IP:8080/sse?token=YOUR_TOKEN"}}}
```
## Local Control Tools
### Core Primitives
| Tool | Description |
|------|-------------|
| `shell(command)` | Execute shell command (bash/cmd/powershell) |
| `python_exec(code)` | Execute Python code with full system access |
| `screen_capture(path)` | Capture desktop screenshot |
### Convenience Tools
| Tool | Description |
|------|-------------|
| `file_read(path)` | Read file content |
| `file_write(path, content)` | Write file content |
| `file_list(path, pattern)` | List directory contents |
| `file_delete(path)` | Delete file or directory |
| `file_copy(src, dst)` | Copy file or directory |
| `file_move(src, dst)` | Move/rename file or directory |
| `clipboard_get()` | Get clipboard content |
| `clipboard_set(content)` | Set clipboard content |
| `system_info()` | Get OS, CPU, memory, disk info |
| `process_list()` | List running processes |
| `process_kill(pid/name)` | Kill a process |
### What You Can Do
```python
# Volume control (Windows)
shell("powershell (Get-AudioDevice -Playback).SetMute($false)")
# Take a photo with webcam
python_exec("""
import cv2
cap = cv2.VideoCapture(0)
ret, frame = cap.read()
cv2.imwrite("photo.jpg", frame)
cap.release()
""")
# Create Excel spreadsheet
python_exec("""
import openpyxl
wb = openpyxl.Workbook()
ws = wb.active
ws['A1'] = 'Sales Report'
ws['A2'] = 1000
wb.save('report.xlsx')
""")
# System maintenance
shell("cleanmgr /d C:") # Windows disk cleanup
shell("sudo apt autoremove") # Linux cleanup
# Reboot computer
shell("shutdown /r /t 60") # Windows
shell("sudo reboot") # Linux
# Kill a program
process_kill(name="notepad.exe")
```
## Browser Tools
### Navigation
| Tool | Description |
|------|-------------|
| `goto(url)` | Navigate to URL |
| `get_url()` | Get current URL |
| `get_title()` | Get page title |
| `reload()` | Reload page |
| `go_back()` | Go back in history |
| `go_forward()` | Go forward in history |
### DOM & Input
| Tool | Description |
|------|-------------|
| `get_text(selector)` | Get element text |
| `get_html(selector)` | Get element HTML |
| `click(selector)` | Click element |
| `type_text(selector, text)` | Type into input |
| `select_option(selector, value)` | Select dropdown |
| `check_box(selector, checked)` | Check/uncheck |
| `scroll_to(x, y)` | Scroll page |
### Screenshots & PDF
| Tool | Description |
|------|-------------|
| `screenshot(path)` | Take screenshot |
| `pdf(path)` | Generate PDF |
### Cookies & Storage
| Tool | Description |
|------|-------------|
| `get_cookies()` | Get cookies |
| `set_cookie(name, value)` | Set cookie |
| `storage_get(key)` | Get localStorage |
| `storage_set(key, value)` | Set localStorage |
### JavaScript
| Tool | Description |
|------|-------------|
| `evaluate(script)` | Execute JS |
## CLI Options
```
arche-browser [OPTIONS]
Mode:
--local Enable full local PC control
--no-browser Disable browser tools (requires --local)
Transport:
--sse Run as SSE server for remote access
--port PORT SSE server port (default: 8080)
Browser:
--headless Run Chrome in headless mode
Authentication:
--no-auth Disable token authentication
--token TOKEN Use specific auth token
--show-token Show current auth token
--reset-token Generate new auth token
```
## Architecture
```
arche_browser/
├── __init__.py # Package exports
├── __main__.py # CLI entry point
├── chrome.py # Chrome process management
├── browser.py # Full CDP browser automation
├── server.py # MCP server with all tools
├── auth.py # Token authentication
├── local.py # Local PC control primitives
└── sites/
└── chatgpt.py # ChatGPT-specific client
```
## Security
- **Token Authentication**: Remote SSE servers require authentication by default
- **Explicit Opt-in**: Local PC control requires `--local` flag
- **No Sandbox**: Local control has NO restrictions - use responsibly
## Requirements
- Python 3.10+
- Chrome, Chromium, or Edge browser (for browser tools)
- MCP client (Claude Code, etc.)
## License
MIT
