gecko-mcp automates a real, logged-in browser, so it's powerful by design. This
document explains the threat model, the least-privilege defaults, and how to audit
it before you install — because you should be cautious about third-party code
that can drive your browser (and, optionally, your keyboard and mouse).
Open a GitHub Security Advisory or a regular issue for anything non-sensitive. Please don't post working exploits publicly before a fix.
- It's small and dependency-light. Two runtime deps (
@modelcontextprotocol/sdk,zod); all logic is plain TypeScript undersrc/. Read it in ~20 minutes. - Run it from source instead of
npxif you prefer:git clone … && npm install && npm run build, then point your MCP client atnode dist/index.js. - Released with npm provenance (built on GitHub Actions): the npm page links to the exact source commit + CI run that produced the package, so you can verify the published bytes match this public repo.
npm auditis clean; CI type-checks, builds and unit-tests on every push.
- OS keyboard/mouse is LOCKED by default. The
real_type,real_key,real_clear,move_cursor,real_clickandwindow_boundstools — the only ones that can affect anything outside the browser — refuse to run until you unlock them, either per-session via theenable_os_inputtool (the user just asks) or persistently withGECKO_MCP_ENABLE_OS_INPUT=1. With nothing set, gecko-mcp does browser automation only. - Real OS input is double-guarded even once unlocked: input is sent only after the browser window is verified foreground, and mouse clicks must land inside that window — otherwise it aborts without sending anything. Payloads go to PowerShell base64-encoded via process-private env vars (no shell interpolation, no temp files).
- Navigation is host-gated: only
http(s)(andabout:blank), and loopback/ private hosts are refused, so a prompt-injected agent can't pivot onto the local API or your LAN. OptionalGECKO_MCP_ALLOW_DOMAINSallowlist. - Cookie values are redacted by default;
upload_filecan be confined withGECKO_MCP_ALLOW_UPLOAD_DIRS;get_valueis flagged as able to read secrets. - MCP tool annotations mark each tool read-only vs destructive, so your client can ask for confirmation on consequential actions.
- No
evaluatetool — arbitrary page-JS execution is deliberately not exposed.
- Prompt injection / "lethal trifecta." The assistant reads untrusted page content and can act on your logged-in sessions. Don't run automation unattended on sites you don't trust. Disable the browser's automation flag when idle.
- The browser's automation API is unauthenticated on localhost (Floorp's
:58261, or Marionette) — any local process can use it while it's enabled. Turn it off when you're not automating. SetGECKO_MCP_TOKENif your build enforces it.
See the README's Security section for the full list and environment variables.