<div align="center">

Arthur

Lightweight Headless Chromium Runtime & MCP Server for AI Agents

<p align="center"> Direct CDP WebSockets • Semantic Ref-ID Snapshots • Persistent Python REPL • FastMCP Server </p>

</div>

---

What is Arthur?

Arthur is a single-command headless browser runtime and Model Context Protocol (MCP) server for AI agents.

It connects directly to Chromium via Chrome DevTools Protocol (CDP) WebSockets without requiring browser extensions, virtual displays (X11/VNC), or heavy automation drivers. One command launches the MCP server, boots an isolated headless Chromium process, and provides your AI agent with full procedural browser control.

Agent / MCP Client
       │
       ▼  execute_python(code)
FastMCP Server (stdio / Streamable HTTP)
       │
       ▼
Python REPL Session (stateful memory & auto-snapshots)
       │
       ▼
Arthur Browser API (synchronous facade)
       │
       ▼  CDP WebSockets
Headless Chromium (--headless=new)

---

Quickstart

You don't need to clone the repository or install dependencies manually. Arthur runs instantly via uvx.

1. Local Desktop (Claude Desktop, Cursor, Goose)

Add Arthur to your MCP settings file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "arthur": {
      "command": "uvx",
      "args": ["arthur-runtime", "mcp"]
    }
  }
}

When your AI agent calls the browser, Arthur automatically discovers local Chrome/Chromium, starts the headless browser, executes actions, and cleans up when finished.

---

2. Docker Container (Self-Contained Streamable HTTP)

Run Arthur in a lightweight, self-contained Debian Slim container with headless Chromium, tini PID 1 process management, and native multi-arch support (amd64 / arm64):

Run via Docker:

docker run -d \
  --name arthur \
  -p 8000:8000 \
  --shm-size=1g \
  --restart unless-stopped \
  sh7vansh/arthur:latest

Or Run via Docker Compose:

docker compose up -d

Connect Your MCP Client:

{
  "mcpServers": {
    "arthur": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

---

3. Remote Server / Cloud (Direct Python via uvx)

To run Arthur on a remote VM, VPS, or cloud server without Docker:

Start the Server:

uvx arthur-runtime mcp --transport streamable-http --stateless --host 0.0.0.0 --port 8000

Connect Your MCP Client:

{
  "mcpServers": {
    "arthur": {
      "url": "http://YOUR_SERVER_IP:8000/mcp"
    }
  }
}

Stateless Streamable HTTP is resilient to network drops and works seamlessly behind Nginx, Cloudflare Tunnels, and AWS ALBs while keeping browser tabs and Python variables in server memory.

---

4. Interactive Terminal Shell (For Testing)

Test the browser directly from your terminal:

uvx arthur-runtime repl

Arthur Interactive REPL (Type 'exit()' or press Ctrl+D to exit)
Global 'browser' instance is available.
arthur> browser.navigate('https://example.com')
arthur> print(browser.snapshot())
arthur> browser.click(1)

---

How It Works

Arthur handles the entire browser lifecycle in a single self-contained process:

1. Automatic Discovery: Locates installed Chrome, Chromium, Brave, or Edge on Linux, macOS, or Windows.
2. Ephemeral Sandbox: Boots Chromium with --headless=new and an isolated temporary user-data directory.
3. CDP WebSockets: Communicates directly over local WebSockets for low-latency element targeting and input simulation.
4. Automatic Teardown: Gracefully shuts down the Chromium subprocess and purges temporary files when the session ends.

---

Python API Reference

When your AI agent uses the execute_python tool, the synchronous browser instance is pre-injected:

# Navigation & Page State
browser.navigate("https://example.com", timeout=30.0)
print(browser.snapshot())                # Semantic Ref-ID outline ([#1], [#2])
print(browser.url, browser.title)

# Interactions (Ref-ID, String Ref, or CSS Selector)
browser.click(1)                         # Click Ref-ID #1
browser.click("button.submit-btn")       # CSS selector fallback
browser.type(2, "search query", press_enter=True)
browser.select(3, "Option Value")
browser.hover(1)
browser.scroll(x=0, y=500)

# Waiting & Synchronization
browser.wait_for(1, state="visible", timeout=10.0)
browser.wait_for_url(r"^https://example\.com/dashboard", timeout=15.0)

# Page Evaluation, Forms & Extraction
result = browser.eval_js("window.innerWidth")
items = browser.extract_items("article.post", {"title": "h2", "link": "a@href"})
browser.fill_form({"Email": "test@test.com"}, submit="Sign In")
png_bytes = browser.screenshot()
text = browser.get_text(1)
attr = browser.get_attribute(1, "data-custom")

# Fast Native Media Control (Zero-DOM)
state = browser.media.status()           # HTML5 media state & player metadata
browser.media.toggle()                   # Toggle play/pause
browser.media.play()                     # Resume playback
browser.media.pause()                    # Pause playback
browser.media.seek(15.0)                 # Seek relative seconds (+15s / -10s)
browser.media.set_volume(0.8)            # Set volume level (0.0 to 1.0)

# Multi-Tab Control & Help
new_tab = browser.new_tab("https://google.com")
all_tabs = browser.tabs
active = browser.active_tab
browser.close_tab(2)
print(browser.help())                    # Built-in formatted SDK quick reference

---

Key Features

• Semantic Ref-ID Snapshots: Generates compact, token-efficient accessible DOM trees with assigned numbers ([#1], [#2]), avoiding brittle XPath or long CSS selectors.
• Fast Media Controller (browser.media): Zero-DOM media playback manipulation that penetrates open Shadow DOM roots without expensive snapshot recalculation.
• Persistent Python REPL: State, variables, imports, and custom functions persist across agent tool calls.
• Single-Turn Self-Healing: Automatically attaches a diagnostic DOM snapshot ([diagnostic_auto_snapshot]) and fuzzy suggestions whenever an error occurs, allowing agents to self-heal in a single turn.
• MCP Resources & Prompts: Built-in MCP resources (arthur://docs/api, arthur://docs/workflow) and structured prompts (browser_automation, media_control) for intelligent agent onboarding.
• Token Budgeting & Defanging: Truncates large outputs to prevent context window explosion and sanitizes tracking image beacons ([IMAGE_BLOCKED]).

---

Local Development

If you want to contribute or build from source:

# Clone and install dependencies
git clone https://github.com/sh7vansh/arthur.git
cd arthur
uv sync --all-extras

# Run tests
uv run pytest

# Run type checker
uv run mypy src

---

License

This project is licensed under the MIT License — see the LICENSE file for details.