Skip to main content
Glama

🌊 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 exactly where you left it.

πŸ§ͺ Test πŸ›‘οΈ Quality πŸ“Έ Image Builder πŸ“– Wiki License: MIT Docker FastMCP


The whole idea, in one breath

Open a browser once. It stays alive (same page, same cookies, same scroll position) while an agent works a task one call at a time, or an n8n workflow steps from node to node. Nothing relaunches, nothing logs in twice.

   agent  ──── MCP  /mcp ─────▢  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                 β”‚ selenium-flow β”‚ ─────▢ β”‚ Selenium Grid β”‚ ──▢ 🌐
workflow  ──── HTTP /browser ──▢ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                  holds no browser          the browser
                                                            lives here

The browser lives on the Grid, so the server can restart without anyone losing a tab. Keep its records in Redis and it remembers whose browser is whose across the restart too.


Related MCP server: Browser MCP

🧰 Every action, both ways

Twenty actions, each an MCP tool and an HTTP endpoint with one schema between them. Hand a whole job to an agent, or drive the same steps yourself from an n8n HTTP node.

Action

open_session

Start a browser: Chrome or Firefox, any window size

navigate

Go to a URL

interact

Click, double-click, right-click, hover, scroll to

drag

Drag onto another element, or by an offset

write

Type into a field, or type a secret nobody sees

press_key

Press Tab, Enter, the arrows

extract

Read text and HTML off the page

outline

What is on the page, with a checked selector for each thing

assert

Wait until JavaScript comes back true, or fail

screenshot

A PNG of the viewport, the whole page or one element

print

Keep the page as a PDF or as HTML

execute_script

Run JavaScript: the escape hatch

frame

Step into an iframe and back out

dialog

Answer an alert, confirm or prompt

resize

Change the window at any time

upload_file

Put a file into a file input

save_site_data

Keep cookies and storage for the next browser

network_body

One captured response body

await_control

Wait for a person to hand the browser back

end_browser

Give the Grid slot back, keep the workspace

Most of them take an optional url: if the browser is somewhere else it goes there first, so you can jump straight to a page in one call. Every parameter and return field is on the wiki, generated from the live tool schemas.


🧠 Workspaces outlive browsers

Name your workspace, with ?workspace=research-bot on the URL or an Sf-Workspace header, and you get the browser that belongs to that name. There is no session id anywhere. Call again with the same name after a reconnect, a restart or a week away, and you are back on the same browser at the same page.

When the Grid reaps an idle browser, or an admin ends one, the workspace keeps the page it was on and the settings it was opened with, so recovery is one call:

open_session()      # back where you were, with the settings you chose

Between calls the server keeps your browser alive for 15 minutes, so an agent that stops to think doesn't come back to an empty page. workspace://current says where you are without opening anything.


πŸ‘€ Watch it live, and take the wheel

The admin UI shows each workspace's browser live in its Live tab. When an agent hits a captcha or a sign-in it can't do, take control. While you hold it, the agent's calls that would change the page are refused and its reads still answer. Solve it and hand back: the agent, waiting in await_control, learns which pages you went through.


πŸ” Flows: do it once, run it forever

Drive a form once, save the steps under a name, and every run after that is one call:

run_flow(name="sign-up", params={"email": "a@example.com"})

A step is a tool call, checked against the live schemas when it is saved. A flow runs in whatever browser you hold, so the same flow checks Chrome and then Firefox without an edit. Give it sites and paths, and a result on a matching page names it in flows_here, so an agent finds the flow for the page it is on. Every workspace has its own library beside a shared global one.


πŸ” Secrets: typed, never shown

Mount credentials the way Kubernetes mounts a Secret (a directory per secret, a file per key) and say which sites each may be typed on. An agent sees names and keys, never a value, and binds one where the value goes:

write(selector={"css": "#password"}, secret={"name": "nextcloud", "key": "password"})

The server types it. If the value shows up later in a page, a result or a resource, it comes back as [secret:nextcloud/password]. A secret is refused on any site it wasn't allowed on.


πŸͺ Sign in once

save_site_data keeps the cookies, localStorage and sessionStorage of the sites a workspace visited. The next browser, even one reopened after a reap, has them restored before its first page loads, so the agent is still signed in.


🧾 See what the page saw

open_session(capture=true) keeps the browser's console and network traffic, masked, at workspace://console and workspace://network. A call that set off a page error says so in its result, and network_body fetches the response behind a failing request.


πŸ—‚ Screenshots, prints, downloads and recordings

Give the server a data directory and every screenshot and print is kept with the workspace, outliving the browser. Downloads are listed while the browser lives, and keep_file saves one before it goes. Turn on recording and a browser opened with record=true has its whole life filmed by the Grid, filed into the workspace's Recordings. Every file comes with a time-limited signed link to hand to someone, or drop into an <img>.


πŸ“– It teaches you how to use it

The server ships an Agent Skill at skill://selenium-flow/SKILL.md: seven rules, a whole task end to end, and a table of when to reach for each tool. Eight references, from reading pages to troubleshooting, are each their own resource, so an agent loads only the one its task needs.

A client that speaks the agents extension also finds the explorer, a subagent that explores a site in your workspace, runs the flows that fit each page, saves new ones and reports back.


πŸ–₯ The admin UI and MCP Apps

Open the server's root for every workspace: its browser, live screen, files, flows, saved site data, history and captured traffic. Sign in with the server's token or, for an admin role, through your OIDC provider.

Hosts that render MCP Apps get show(uri), which draws any resource the server serves inline: your workspace, its files, flows, secrets and the skill. A client that can't read resources gets list_resources and read_resource instead.


πŸš€ Quick start

git clone https://github.com/kubed-io/selenium-flow.git && cd selenium-flow
docker compose up --build

That starts the server on port 8000 with a Chromium Grid beside it, and auth off. Open a browser over HTTP:

curl -X POST localhost:8000/browser \
  -H 'Sf-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?workspace=demo, and open http://localhost:8000 to watch the demo workspace in its Live tab. πŸ‘€

In production, set AUTH_TOKEN and send it as Authorization: Bearer <token>. Every setting is a config file key, an environment variable and a flag: see Configuration.


πŸ“š Where next


πŸ“œ Licence

MIT. See LICENSE.

Not affiliated with, endorsed by, or sponsored by the Selenium project. "Selenium" is a trademark of the Software Freedom Conservancy, used here only to identify the software this server drives.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to drive a real, logged-in Chrome browser for web automation tasks like navigation, clicking, typing, and screenshotting.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to control a real local browser window for web automation tasks such as clicking, typing, scrolling, and taking screenshots.
      184 npm
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and MCP clients to automate web browsers via Selenium WebDriver, supporting Chrome, Firefox, and Edge in headless or visible mode with tools for navigation, interaction, content extraction, screenshots, and scripting.
      21
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables remote agents to control a local Chrome/Edge browser via MCP, supporting navigation, snapshots, clicks, typing, screenshots, and script execution.
      25 npm
      ISC