Home

selenium-flow

One browser, many calls. Drive a real Chrome or Firefox on Selenium Grid from an agent over MCP, or from anything else over plain HTTP — same actions, same server, one browser that stays where you left it.

The README is the tour. This is the manual.

Where to go

You want to	Read
Connect a client — Claude, VS Code, n8n, Cursor, curl	Installing
Run the server — stdio, HTTP, Docker, Kubernetes	Deployment
Name a workspace, or recover a dead browser	Workspaces
Make a token, use the admin UI, share a file	Administration
Look up one action's parameters	Actions
Save a sequence and replay it in one call	Flows
Type a password nothing ever shows you	Secrets
See what a workspace has, and keep a download or a screenshot past the browser that made it	Files

The shape of it

   agent  ──── MCP  /mcp ─────▶  ┌───────────────┐        ┌───────────────┐
                                 │ selenium-flow │ ─────▶ │ Selenium Grid │ ──▶ 🌐
workflow  ──── HTTP /browser ──▶ └───────────────┘        └───────────────┘
                                  holds no browser          the browser
                                                            lives here

The server holds no browser. The browser lives on the Grid, and the caller names the workspace that holds it, so the server can restart or scale to zero without anyone losing a tab.

Two consequences worth knowing before you start:

• State carries over. Log in once and every later call is logged in. But a browser left on the wrong page makes your next XPath fail for a reason that has nothing to do with the XPath.
• Slots are scarce. The Grid runs a handful of browsers in total, and an abandoned one holds its slot until it is reaped. Closing is capacity, not politeness.

Ten seconds in

docker compose up --build

That starts the server and a Grid for it to drive, with auth off. Then:

curl -X POST localhost:8000/browser \
  -H 'X-Workspace: demo' -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "width": 1280, "height": 800}'

Point an MCP client at http://localhost:8000/mcp, open the admin UI at localhost:8000, and watch the browser work at localhost:7900.