gecko-mcp

gecko-mcp

An MCP (Model Context Protocol) server that lets AI assistants — Claude Code,

Claude Desktop, Cursor, and any MCP client — **read pages, take screenshots and

manage tabs in [Floorp](https://floorp.app) and other Firefox-based browsers**

(LibreWolf, Waterfox, Zen, Mullvad, Firefox…), using your real, logged-in session.

Think "Claude in Chrome", but for the whole Firefox/Gecko family.

Get started in ~30 seconds:

npx gecko-mcp setup

Registers gecko-mcp with Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, Zed, Codex and more — per-project or global. See Setup for manual config and Requirements for the one-time browser step.

Cautious about installing this? Good — you should be. It's small (2 deps, all

in src/), the OS keyboard/mouse is locked by default (browser-only

until you opt in), releases ship with npm provenance (verifiable against this

source), and the full threat model is in SECURITY.md. Read it

before you run npx gecko-mcp.

How it works

gecko-mcp talks to the browser through one of two backends, picked automatically:

• Floorp ships a built-in automation HTTP API. Set floorp.mcp.enabled = true in about:config and gecko-mcp uses the fast http://127.0.0.1:58261 API — no extension, richest feature set.
• Any other Gecko browser — launch it with Marionette (the automation engine built into every Firefox fork) and gecko-mcp drives your live session over it. Same tools, same real session.

  Claude Code / Desktop / Cursor

│ MCP (stdio) ▼ gecko-mcp ──► Floorp :58261 (built-in API) ─┐ (this project) ──► Marionette :2828 (any Gecko fork) ─┴─► your real tabs

Requirements

• A Firefox-based browser installed and running, with automation enabled:
• Floorp: set `floorp.mcp.enabled` to true in about:config, restart Floorp.
• Other forks (LibreWolf / Waterfox / Zen / Mullvad / Firefox): launch the browser with `-marionette` (see Browser support).
• Node.js ≥ 18.

Setup

Quick start — the setup wizard

npx gecko-mcp setup

An interactive wizard registers gecko-mcp with the AI coding tool(s) of your choice — Claude Code, Cursor, Windsurf, VS Code (Copilot), Gemini CLI, Codex, Zed, Cline (and a copy-paste snippet for Kimi Code, Antigravity, or any other MCP client) — and lets you install it for the current project or globally (all repos). It merges into existing config (and backs it up first).

Non-interactive / scriptable:

npx gecko-mcp setup --list                          # show supported tools

npx gecko-mcp setup --tool claude-code,cursor --scope global npx gecko-mcp setup --tool codex --scope global --print # dry run

Manual

Any MCP client works with this server block (no clone/build needed — npx fetches it):

{

"mcpServers": { "gecko": { "command": "npx", "args": ["-y", "gecko-mcp"] } } }

Or with Claude Code's CLI: claude mcp add gecko -s user -- npx -y gecko-mcp.

One-time Floorp step: set floorp.mcp.enabled = true in about:config and

restart Floorp so its automation API is available.

Browser support

gecko-mcp picks its backend automatically: if Floorp's :58261 API is reachable it uses that; otherwise it connects to Marionette, the automation engine built into every Gecko browser. To use a non-Floorp browser, launch it once with Marionette enabled:

Marionette listens on TCP 2828 by default. To use another port, set the marionette.port pref in the profile (e.g. via user.js) and start gecko-mcp with a matching MARIONETTE_PORT. Force a backend with GECKO_MCP_BACKEND=marionette.

Note: Marionette must be enabled *at launch* to attach to your live session.

On the Marionette backend, Floorp-only extras (snapshot fingerprints,

list_workspaces/switch_workspace, accessibility tree) return a clear

"not supported" message — use find / read_page instead. Everything else

(tabs, navigation, click, type, forms, screenshots, cookies, real OS input…) works.

Tools

Tabs & reading

Interaction

Most tools target the active tab by default; pass a browserId (from list_tabs) to target a specific tab.

OS keyboard & mouse — locked by default 🔒

The tools below can affect things *outside* the browser, so they are disabled until you turn them on. With nothing set, gecko-mcp does browser automation only. Unlock them per-session by just asking ("enable OS input", which calls the enable_os_input tool), or persistently with GECKO_MCP_ENABLE_OS_INPUT=1. Lock again with disable_os_input. While locked, these tools refuse with a clear message.

The `evaluate` tool (run arbitrary page JavaScript) is locked the same way — unlock with enable_evaluate or GECKO_MCP_ENABLE_EVALUATE=1.

Real OS keyboard (Windows) — for React/rich editors and bot-guarded submits that ignore synthetic input:

These produce input a page can't distinguish from a human's, so they drive React/Slate editors and submit composers that synthetic clicks/typing can't. Workflow: click the field to focus it → real_clear / real_type / real_key "Enter".

Safety guard: OS keystrokes go to the foreground window, so before sending

anything these tools bring Floorp to the foreground and verify it — if Floorp

isn't running or can't be focused, they abort without typing a single key, so

input can never leak into another app.

Real OS mouse (Windows) — genuine isTrusted clicks at screen coordinates:

Double guard: the click is sent only when Floorp is verified foreground and

the point lies inside Floorp's window rect — a stray coordinate is refused, so

a click can never land in another app/window. Coordinates are screen pixels

(note display scaling/DPI when mapping from a screenshot).

More interaction & queries

Security

Understand the threat model before enabling this. Two risks dominate:

1. Floorp's automation API has no authentication by default. While floorp.mcp.enabled is on, any local process can drive your logged-in browser via 127.0.0.1:58261 — not just this server. There is also no Origin check, so hostile web pages may attempt CSRF/DNS-rebinding tricks against it. Mitigations:

• Turn floorp.mcp.enabled off when you're not using automation.
• Set the GECKO_MCP_TOKEN environment variable — this server then sends it as a Bearer token on every request (effective on Floorp builds that enforce a token; harmless otherwise).

1. Prompt injection ("lethal trifecta"). The assistant reads untrusted page content *and* can act on your authenticated sessions (click, type, submit, navigate, real OS input). A malicious page could try to instruct the assistant to act against you. Treat everything read from a page as untrusted; don't run automation unattended on sites you don't trust.

Hardening built into this server:

• OS keyboard/mouse is locked by default (least privilege): the only tools that can act outside the browser refuse to run until you explicitly unlock them (enable_os_input tool, or GECKO_MCP_ENABLE_OS_INPUT=1). By default gecko-mcp can only automate the browser, never your wider machine.
• Real OS input is double-guarded: keys/clicks are sent only after verifying Floorp is the foreground window, and mouse clicks must land inside Floorp's window rectangle — otherwise it aborts *without* sending anything. Po