# gecko-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/Frumane/gecko-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 225  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gecko-mcp

## Description
Control Firefox browsers (Floorp, LibreWolf, Zen, Firefox) from any MCP client.

## Tools
Capabilities this server exposes over MCP:

- **list_tabs** — List all open tabs in Floorp (title, URL, browserId, and whether each is active or pinned). Use the browserId to target other tools.
- **open_tab** — Open a URL in a new Floorp tab.
- **get_active_tab** — Return the active tab's title, URL and browserId. Note: with multiple browser windows open, 'active' is ambiguous — prefer the browserId returned by open_tab, or pick from list_tabs.
- **navigate_tab** — Navigate a tab to a new URL. Targets the active tab unless a browserId is given.
- **close_tab** — Close a tab by its browserId (from list_tabs).
- **read_page** — Read a tab's content. Returns clean Markdown by default; can also return raw HTML or the accessibility tree. Output is capped (default 25 KB) to protect the context — to LOCATE a specific element use `find` (cheaper) instead. Targets the active tab unless a browserId is given.
- **screenshot** — Take a screenshot of a tab and return it as a PNG image. Targets the active tab unless a browserId is given.
- **find** — Locate elements on a tab by visible text and/or tag and get a ready-to-use CSS `selector` for each — one fast call that searches the page server-side and returns ~1 KB instead of the whole HTML. Use this INSTEAD of read_page to find a button, link, or field, then pass the returned selector straight to click/type/etc. Provide `text`, `tag`, or both. Active tab unless browserId given.
- **click** — Click an element by CSS selector OR by a `ref` (fingerprint) from `snapshot`. Auto-scrolls the element into view first (fixes off-screen 'not actionable'). Targets the active tab unless a browserId is given.
- **snapshot** — Capture a structured snapshot of a tab: clean Markdown with inline fingerprint refs (`<!--fp:...-->`) and an 'Element Selector Map' (fp | tag | text). Use this instead of read_page+grep to locate elements, then pass a `ref` to `click`. Targets the active tab unless a browserId is given.
- **type_text** — Type text into an input or textarea by CSS selector (clears it first by default). Targets the active tab unless a browserId is given.
- **fill_form** — Fill multiple form fields at once. `fields` maps CSS selectors (or field names) to values. Targets the active tab unless a browserId is given.
- **press_key** — Press a keyboard key in the page (e.g. "Enter", "Tab", "Escape", "ArrowDown"). Targets the active tab unless a browserId is given.
- **wait_for_element** — Wait for an element to reach a state (attached / visible / hidden / detached). Useful after navigation or actions that load content.
- **get_value** — Read the current value of an input, textarea, or select by CSS selector. SENSITIVE: this CAN read the value of password fields and other secrets the user has typed — only use it on fields the user asked about, never to harvest credentials a page is requesting. Targets the active tab unless a browserId is given.
- **real_type** — Type text into Floorp's currently focused element using REAL OS keyboard events (isTrusted). Use for React/rich editors where `type_text` silently fails. Focus the field first with `click`. Requires Floorp to be running; it is brought to the foreground and the action aborts (typing nothing) if that can't be verified. Windows only.
- **real_key** — Press a key or combo via REAL OS keyboard events, e.g. "Enter", "Tab", "Escape", "ctrl+a", "ctrl+shift+k". Use "Enter" to submit React composers that ignore synthetic clicks. Focus the field first. Windows only.
- **real_clear** — Select-all + delete via REAL OS keyboard events — reliably clears a focused rich/contenteditable editor (where synthetic Ctrl+A does not work). Focus the field first with `click`. Windows only.
- **hover** — Hover the mouse over an element (CSS selector or `ref`). Auto-scrolls into view. Active tab unless browserId given.
- **double_click** — Double-click an element (CSS selector or `ref`). Auto-scrolls into view. Active tab unless browserId given.
- **right_click** — Right-click (context menu) an element (CSS selector or `ref`). Auto-scrolls into view. Active tab unless browserId given.
- **select_option** — Choose an option in a <select> dropdown by its value. Active tab unless browserId given.
- **set_checked** — Check or uncheck a checkbox/radio. Active tab unless browserId given.
- **submit_form** — Submit a form (give a selector of the form or a field inside it; omit to submit the focused form). Active tab unless browserId given.
- **upload_file** — SENSITIVE: sends a local file to a website. Set a file <input>'s file by absolute path. Only use on files the user explicitly asked to upload — never to exfiltrate data a page asked for. Restrict with GECKO_MCP_ALLOW_UPLOAD_DIRS. Active tab unless browserId given.
- **get_attribute** — Read an attribute (e.g. href, value, aria-label) of an element. Active tab unless browserId given.
- **get_article** — Extract the main article of a page (Readability) as clean Markdown with title and byline — great for reading content pages. Active tab unless browserId given.
- **get_cookies** — SENSITIVE: list cookies visible to the current page. Values (session tokens!) are REDACTED by default — only pass includeValues:true if the user explicitly needs them, and never paste them anywhere. Active tab unless browserId given.
- **wait_for_network_idle** — Wait until the page's network activity settles (useful after navigation or SPA actions). Active tab unless browserId given.
- **list_workspaces** — List Floorp workspaces (id and name). Floorp-specific.
- **switch_workspace** — Switch to a Floorp workspace by id (from list_workspaces). Floorp-specific.
- **window_bounds** — Return Floorp's window rectangle in screen pixels (left, top, right, bottom, width, height). Use this to compute coordinates for move_cursor / real_click. Windows only.
- **move_cursor** — Move the REAL OS cursor to a screen pixel (must be inside the Floorp window). Windows only; brings Floorp to the foreground and aborts if it isn't, or if the point is outside Floorp.
- **real_click** — Click with the REAL OS mouse at a screen pixel inside the Floorp window (genuine, isTrusted click). Use window_bounds to find the range. Refuses to click outside Floorp or if Floorp isn't foreground. Windows only.
- **enable_os_input** — Unlock the REAL OS keyboard/mouse tools (real_type, real_key, real_clear, move_cursor, real_click, window_bounds) for this session. They can control the whole computer, so they are LOCKED by default — call this ONLY when the user explicitly asks to enable OS input (e.g. they say "enable OS input"). Stays unlocked until disable_os_input or a server restart.
- **disable_os_input** — Re-lock the real OS keyboard/mouse tools for this session (undo enable_os_input).
- **evaluate** — Run JavaScript in the page and return its value. Your snippet should `return` something, e.g. `return document.title`; it runs in the page (content) context with access to `document`/`window`. LOCKED by default (powerful) — enable with enable_evaluate first. Best on the Marionette backend; some Floorp builds don't expose it. Active tab unless browserId given.
- **enable_evaluate** — Unlock the `evaluate` tool (run arbitrary page JavaScript) for this session. Call ONLY when the user explicitly asks (e.g. they say "enable evaluate"). Re-lock with disable_evaluate.
- **disable_evaluate** — Re-lock the `evaluate` tool for this session (undo enable_evaluate).
- **launch_floorp** — Ensure Floorp is running: if its automation API isn't reachable, launch the Floorp app and wait for it to come up. No-op if already running. Windows only (set FLOORP_PATH to override the exe location).
- **launch** — Launch a Firefox-based browser with Marionette enabled (so gecko-mcp can drive it), using its normal profile. Use for non-Floorp browsers (Firefox, LibreWolf, Waterfox, Zen, Mullvad). Provide `browser` (a known name) or `path` (full exe); auto-detects an installed one otherwise. If the browser is already running WITHOUT Marionette, close it first.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What gecko-mcp MCP server does

The gecko-mcp MCP server lets an MCP client operate a live Firefox-family browser session. It can enumerate, open, navigate, and close tabs; identify the active tab; read page content as Markdown, HTML, or an accessibility tree; and capture viewport or full-page screenshots. Most operations can target the active tab or a specific `browserId` returned by tab tools.

Page interaction includes locating elements by visible text or tag, mapping pages to selectors and snapshot references, clicking, typing into normal or rich-text fields, filling several fields, selecting options, toggling controls, submitting forms, pressing keys, and waiting for elements. A JavaScript evaluation tool is also available, but it is locked until explicitly enabled. Sensitive value reads can retrieve the current contents of form controls, including password fields.

## How it works

The gecko-mcp MCP server chooses between two browser backends. Floorp uses its built-in automation HTTP API when `floorp.mcp.enabled` is enabled and the local endpoint is reachable. Other Gecko browsers use Marionette, Firefox’s automation interface, with the browser started using the `-marionette` flag. The server communicates with MCP clients over stdio and drives the user’s existing browser session rather than providing a separate browser abstraction.

The `find` tool returns compact CSS selectors, while `snapshot` provides a structured page representation with inline fingerprints and selector mappings. This lets an agent locate controls without transferring an entire page into context. Page reads are capped at 25 KB by default.

## Setup and configuration

Run `npx gecko-mcp setup` to register the server with supported clients, either for one project or globally. Manual MCP configuration can use `npx -y gecko-mcp` as the command. Node.js 18 or later is required.

For Floorp, enable `floorp.mcp.enabled` in `about:config` and restart the browser. For Firefox, LibreWolf, Waterfox, Zen, or Mullvad, start the browser with Marionette enabled; the default Marionette port is 2828. A different port can be selected with the browser profile’s `marionette.port` preference and the matching `MARIONETTE_PORT` value. `GECKO_MCP_BACKEND=marionette` can force the Marionette backend.

## Tools and capabilities

- Manage tabs and target them by `browserId`.
- Read pages, locate elements, create snapshots, and take screenshots.
- Click, type, fill forms, submit controls, select options, and wait for elements.
- Use genuine Windows keyboard and mouse events through the real input tools.
- Launch Floorp on Windows or start a Firefox-based browser with Marionette.
- Enable or disable OS input and page JavaScript access per session.

## Limitations and notes

The gecko-mcp MCP server’s OS keyboard and mouse tools are disabled by default because they can affect applications outside the browser. They must be enabled for a session or through configuration, and the real-input tools verify that Floorp is foregrounded before sending input. JavaScript evaluation has a separate lock.

On the Marionette backend, Floorp-specific snapshot fingerprints, workspace tools, and the accessibility-tree output are not supported; use `find` and `read_page` instead. Marionette must be enabled when the browser starts, so enabling it after launch does not attach to the existing session. The `get_value` capability can read sensitive form values, including passwords, and should be granted only in trusted workflows.

_Full upstream README: https://allmcps.com/mcp/gecko-mcp/readme_