agent-viewer

Give your AI agent a visible browser. agent-viewer is an MCP server (plus a standalone HTTP bridge) that lets a model drive a real Chromium window — and you can watch it work, because a virtual cursor glides to each target and clicks.

Features

• MCP server — Cline / Claude Desktop / Cursor / any MCP host gets browser_* tools and can drive the browser on its own.
• Visible cursor overlay — a red dot glides to each target with a click ripple.
• Standalone HTTP bridge — the same engine over http://127.0.0.1:8765, with a small CLI client (av) for scripts or manual use.
• Survives navigation — the overlay is injected on every page via an init script.
• Image-map aware — can click <area> regions of HTML image maps.
• Headful or headless, configurable animation speed, idle auto-shutdown.

Requirements

• Python 3.10+
• Playwright (Chromium is fetched automatically)

Install

pip install agent-viewer-mcp
python -m playwright install chromium

Or from source:

git clone https://github.com/fatunkaz/agent-viewer.git
cd agent-viewer
pip install -r requirements.txt
python -m playwright install chromium

Use it from your AI agent (MCP)

Add the server to your MCP host. For Cline (~/.cline/mcp.json, or the MCP panel in the IDE):

{
  "mcpServers": {
    "agent-viewer": {
      "command": "uvx",
      "args": ["--from", "agent-viewer-mcp", "agent-viewer-mcp"],
      "disabled": false
    }
  }
}

Now the model can call browser_goto, browser_click, browser_type, browser_press, browser_read, browser_eval, browser_screenshot by itself. Full guide (other hosts, env vars, troubleshooting): docs/MCP.md.

Use it standalone (HTTP bridge + CLI)

Terminal 1 — start the bridge (opens a browser window):

python agent_viewer.py            # or: python -m agent_viewer.server

Terminal 2 — drive it with the CLI:

python av.py goto https://example.com
python av.py click "a[href='/about']"
python av.py type "#search" "hello" --submit
python av.py read "#main"
python av.py shot home
python av.py quit

The window stays open between commands, so you can watch each action happen.

How it works

  AI host (Cline/Claude)        agent-viewer (this project)         the web
  ---------------------         ---------------------------         -------
   MCP tool call  ------>   MCP server  (mcp_server.py)   \
                             HTTP bridge (server.py)  ------+-->  Chromium
   av CLI / curl  ------>                                  /      (visible)
                                        |
                                        v
                                 BrowserAgent (browser.py)
                                        |  inject CURSOR_JS on every page
                                        v
                                 move virtual cursor -> real click

Both entry points share the same engine, BrowserAgent (browser.py). The virtual cursor is a DOM element injected into every page (__ac_move / __ac_ripple); real clicks use page.mouse.click at the element center. For <area> elements the center is computed from the image-map polygon and scaled to the rendered image.

More details: docs/ARCHITECTURE.md · docs/MCP.md.

HTTP API

Full reference with curl examples: docs/API.md.

Server options

python agent_viewer.py --port 8765 --speed 1.0 --headless --idle 600

The bridge also shuts itself down if you close the browser window manually.

Project layout

agent-viewer/
|- agent_viewer/            # the package
|  |- browser.py            # shared Playwright engine (visible cursor)
|  |- mcp_server.py         # MCP server -> browser_* tools
|  |- server.py             # Flask HTTP bridge (standalone mode)
|  |- client.py             # CLI client (`av`)
|  |- js.py                 # injected cursor / center JS
|- agent_viewer.py          # compatibility entry point
|- av.py                    # compatibility entry point
|- docs/
|  |- MCP.md                # connect to Cline and other MCP hosts
|  |- API.md                # HTTP API reference
|  |- ARCHITECTURE.md       # how it works
|- requirements.txt
|- pyproject.toml
|- LICENSE

Disclaimer

This project is an educational / RPA demonstration of a visible browser automation agent. It is site-agnostic and ships with no third-party content. Use it responsibly:

• Respect the Terms of Service and robots.txt of any website you automate.
• Do not use it to violate a site's rules, game leaderboards, or scrape content you are not allowed to copy.
• The /eval endpoint executes arbitrary JavaScript in the target page, and the server binds to 127.0.0.1 only — never expose it to a network.

License

MIT (c) 2026 fatunkaz