Ashzo MCP

Ashzo MCP lets an AI agent (Claude, Cursor, Antigravity, Codex, ...) work with websites quickly, and lets you watch it happen live.

• A live dashboard at http://localhost:8000: a live feed, progress, the Flow chat, the agent's browser, and every video it makes, appearing as it happens. No refresh needed.

• A real signed-in browser (the Ashzo Browser) the agent drives and you can watch. You sign in once.

• A fast way to read any site's data: it learns a site's own JSON API and calls it directly, instead of clicking through pages.

• A Google Flow video generator that runs inside the Ashzo Browser, with a playbook for recreating videos.

• A live card inside chats (in apps that support MCP Apps) that shows a video being made, like the Higgsfield card.

Quick start

Windows: double-click CREATE_DESKTOP_ICON.bat. It sets up .venv, installs everything, and puts an Ashzo MCP icon on your desktop. Double-click the icon any time: it starts the local server and opens the dashboard in your default browser.

macOS / Linux:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python -m playwright install chromium
.venv/bin/python create_desktop_shortcut.py     # desktop icon
.venv/bin/python launch_ashzo.py                # or just start it now

No icon? START_ASHZO.bat (Windows) or python launch_ashzo.py does the same thing. Server output goes to logs/ashzo_server.log.

AI agents working in this repo are told (in AGENTS.md, CLAUDE.md and the Cursor/Antigravity rules) to create the icon on a new computer and tell you where it is.

Run with Docker (any OS, no Python setup)

You need Docker Desktop (Windows, macOS) or Docker Engine (Linux).

Windows, no commands: double-click CREATE_DOCKER_ICON.bat once. It builds the app and puts an Ashzo MCP (Docker) icon on your desktop. From then on, double-click that icon: it starts Docker Desktop if needed, starts the app and opens the dashboard.

Or from a terminal, in this folder:

docker compose up -d --build

The first build takes a few minutes (it downloads Chromium). After that:

• Dashboard: http://localhost:8000

• Ashzo Browser: http://localhost:6080/vnc.html. This is the browser the agent works in. Open it once to sign in to Google (for Flow). It is a live view of the browser running inside the container. In the dashboard, Connect and the Open browser view buttons open it for you in a new tab.

• Your data (sign-ins, settings, downloads) is kept in the Docker volume ashzo-data, so it survives restarts and rebuilds. Your downloaded videos are in there too.

Useful commands:

docker compose logs -f ashzo      # server output
docker compose down               # stop (keeps your data)
docker compose down -v            # stop and delete all saved data

Ports are bound to 127.0.0.1, so only this computer can reach them. To protect the noVNC view with a password, create a .env file next to docker-compose.yml containing VNC_PASSWORD=your-password, then run docker compose up -d.

Connect Claude (Windows): the CREATE_DOCKER_ICON.bat setup also registers Ashzo with Claude Desktop and Claude Code, so there's nothing to type. Quit Claude Desktop completely and open it again. Claude Code picks it up in new sessions. Your existing Claude settings are kept, and a .bak copy of each config is made first.

For other AI apps, or to set it up by hand, use docker exec instead of a local Python path. The MCP server runs inside the container and sends its events to the dashboard:

{
  "mcpServers": {
    "ashzo-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "ASHZO_DASHBOARD_URL=http://127.0.0.1:8000", "ashzo-mcp", "python", "server.py"]
    }
  }
}

Limits of the container: Google may ask for extra checks when you sign in from a container, and Flow's pages can change, as they can with the native install. Sign-in and Flow work are not verified in every setup.

Connect it to your AI app

Add the server to your MCP config (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json). Use the full paths on your computer (this is the native install; for Docker, use the docker exec config above):

{
  "mcpServers": {
    "ashzo-mcp": {
      "command": "<repo>/.venv/Scripts/python.exe",
      "args": ["<repo>/server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

(macOS / Linux: <repo>/.venv/bin/python.) The MCP process forwards its events to the dashboard, so the dashboard shows what the agent does even when the agent starts the server itself. Keep the dashboard open (use the desktop icon) to watch.

Related MCP server: Charlotte

The dashboard

Everything below updates live while an agent works through the MCP.

Light and dark themes (and system), with a circular reveal when you switch:

The live card inside a chat

When an agent calls flow_generate_video, apps that support MCP Apps (Claude desktop and web, ChatGPT and VS Code, at the time of writing) show a live card in the conversation: progress, the video, the prompt, reference frames, the last Flow replies, and a Cancel button.

Notes:

• Hosts that don't support MCP Apps still get the normal text result, and the dashboard still shows everything.

• The card tries to play the video from the local dashboard first. If the chat app blocks that, it loads the video in small pieces through the MCP connection instead.

• This part needs mcp 2.3 or newer (pip install -U mcp). With older versions the server works as before, without the card.

How it reads websites: 3 tiers

 agent ── universal_request(url) ──►  Tier 1  Fast Path     replay a learned JSON/GraphQL API with your saved session
                                        │ no route yet, or refused
                                        ▼
                                      Tier 2  Discovery     open the page, watch its network traffic, learn the API, save it
                                        │ the page has no JSON API
                                        ▼
                                      Tier 3  Page text     clean Markdown / accessibility tree from the page

Fast Path is self-healing. If a site refuses the saved session (401/403, or it sends you to a sign-in page), Ashzo opens the site in the Ashzo Browser, lets the site renew its own cookies, notes the fresh request headers (kept in memory for 15 minutes, never written to disk), and tries again. It retries with backoff (up to 5 tries and 2 session renewals per call). If it still can't, it falls back to the browser tiers and says so. After 3 failures in a row a route is paused for 30 minutes, unless you sign in again.

It asks for exactly the URL you asked for. A learned route only supplies the site's headers and auth. It never replaces your URL, so you can't get another page's data.

What the Fast Path cannot do (it falls back to Tier 2 or 3 automatically):

• sites whose tokens are very short-lived or signed per request;

• sites with anti-bot protection or CAPTCHAs (Ashzo does not try to get around those);

• pages that are plain HTML with no JSON API behind them.

Speed and tokens (measured)

Measured on a local test setup. Your numbers will differ by site and network, so treat them as a guide:

Tokens: driving a browser with screenshots costs roughly 1,000 to 1,500 tokens per screenshot, and the context grows with every step. Ashzo's tools return small structured results instead. The tool list costs about 2.3k tokens once per conversation, a status check about 130 tokens, and a full Flow video about 2k tokens (one flow_generate_video plus a few flow_job_status calls).

MCP tools

Google Flow

• GOOGLE_FLOW_SKILL.md is the playbook for agents. Sections 0 and 0.5 are mandatory: generate visibly in the Ashzo Browser, report only real credits, never bypass CAPTCHAs.

• VIDEO_RECREATION_SKILL.md is the video-recreation workflow, and Flow work uses it every time a video is being recreated.

• Flow has no public API. Generation drives Flow's own web page, so its buttons and menus can change; if Flow changes its layout, the selectors in flow_video_automator.py are the place to fix. Everything the automation does is visible in Live View.

• Generated files are saved to downloads/ and listed in the dashboard.

Settings

Open Settings in the dashboard (stored in ashzo_settings.json): your Flow project link, whether the Ashzo Browser window is shown, the browser's debug port (default 9333), sign-in and render timeouts, and the default aspect ratio.

Security and privacy

• The server listens on 127.0.0.1 only, and rejects requests from other websites (host and origin checks).

• Cookies are only ever sent to their own site. Secrets are masked in logs and in files (ya29...7890).

• Sessions, cookies, learned routes and downloads stay on your computer and are in .gitignore. Fresh request headers captured during self-repair are kept in memory only.

• In stdio mode nothing is printed to stdout (that would break the MCP protocol); logs go to stderr and logs/.

• Ashzo reuses your own signed-in browser. It does not solve CAPTCHAs or get around anti-bot checks.

Development

python scripts/verify_dashboard.py       # checks layout, spinner, theme, live updates, no console errors
python scripts/capture_screenshots.py    # refreshes docs/screenshots
python test_server.py                    # the original engine tests
npm install && npm run build:css         # only after changing Tailwind classes in web/

The dashboard is plain HTML/JS with locally compiled Tailwind, fonts and icons (no CDNs), so it works offline. Rules for contributors and agents are in AGENTS.md.

Key files: server.py (MCP tools), app.py (dashboard server and live events), browser_hub.py (the Ashzo Browser), session_refresh.py (Fast Path self-repair), flow_video_automator.py (Flow jobs), web/chat_card.html (the in-chat card).

License

MIT. See LICENSE.