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
Understand whether you pass session_id	Sessions
Make a token, use the admin UI, share a file	Administration
Look up one action's parameters	Actions

The shape of it

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

The server holds no browser. A session lives on the Grid and the caller carries its id, so the server can restart, scale to zero, or sit behind several replicas 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/open \
  -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/admin, and watch the browser work at localhost:7900.