gecko-mcp server

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 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:

in about:config and gecko-mcp uses the fast http://127.0.0.1:58261 API — no extension, richest feature set.

• Floorp ships a built-in automation HTTP API. Set floorp.mcp.enabled = true

engine built into every Firefox fork) and gecko-mcp drives your live session over it. Same tools, same real session.

• Any other Gecko browser — launch it with Marionette (the automation

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

Requirements

browser with -marionette (see Browser support).

• 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

• 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:

Shortened. The full README is on GitHub.