Skip to main content
Glama

spectra_mcp

An MCP server that gives AI agents a stateful anti-detect Firefox powered by invisible_playwright.

Agents can navigate, inspect accessible page snapshots, interact through stable element refs, fill forms, read text, and capture screenshots without managing raw Playwright state.

AI agent ── MCP/stdio ──► spectra_mcp ──► patched Firefox

Highlights

  • Agent-first snapshot → ref → action workflow

  • Automatic fingerprint profile, timezone, and locale selection

  • Humanized mouse movement and browser-level fingerprint patches

  • Typed MCP results and real isError=true failures

  • Secret redaction and environment-based proxy credentials

  • Compact default tool profile for Hermes, OpenClaw, and other agents

Related MCP server: browser-devtools-mcp

Install

Requires Python 3.11+.

git clone https://github.com/LowOrbitLab/spectra_mcp.git
cd spectra_mcp
pip install -e .
python -m invisible_playwright fetch

The patched Firefox download is approximately 100 MB and only needs to run once. The browser dependency is pinned to an exact upstream commit.

MCP configuration

{
  "mcpServers": {
    "spectra_mcp": {
      "command": "/absolute/path/to/venv/bin/spectra_mcp",
      "env": {
        "SPECTRA_MCP_TOOL_PROFILE": "agent"
      }
    }
  }
}

Use an absolute executable path when the client filters subprocess environment variables. Keep parallel tool calls disabled because operations within one browser session are serialized.

Client-specific examples:

Agent workflow

  1. Call binary_status; use binary_install if needed.

  2. Call browser_start.

  3. Navigate with browser_navigate.

  4. Inspect the page with browser_snapshot.

  5. Act through browser_click_ref, browser_set_value_ref, browser_type_text_ref, browser_select_option_ref, or browser_set_form_values.

  6. Use browser_list_tabs and browser_activate_tab when a popup or new tab opens.

  7. Use browser_wait_for for asynchronous text, URL, or element changes.

  8. Read targeted content with browser_find_text or paginated browser_get_text.

  9. Call browser_stop when finished.

Mutating ref actions return a compact refreshed snapshot by default; use observe="full" for structured element/frame arrays or observe="none" to skip observation. Agent tools automatically use the only live session, so models normally do not need to remember a session ID.

Documentation

License

MIT. Firefox remains MPL-2.0. This project downloads the patched browser from upstream releases and does not redistribute it.

Available Tools

19 tools
binary_installA

Download (and verify) the patched Firefox binary if not already cached.

One-time ~100 MB download, SHA256-verified. Set force=True to re-download even if a cached copy exists. Call this before session_start. Reports download progress (0-100%) when the server reports a size and the client supports progress tokens; phase changes (downloading/verifying/extracting) are always logged.

Inputs: force. Returns: result

binary_statusA

Report whether the patched Firefox binary is already cached locally.

Returns the cache path, version, and a ready flag. Does NOT download.

Inputs: no named parameters. Returns: result

browser_activate_tabC

Switch the agent browser to an existing tab by page_id.

Inputs: page_id (required), session_id. Returns: result

browser_click_refB

Click a ref from browser_snapshot and return the updated snapshot.

Inputs: ref (required), observe, session_id, timeout_ms. Returns: result

browser_find_textB

Find text in the active page and return short surrounding snippets.

Inputs: query (required), session_id, max_results, context_chars. Returns: result

browser_get_textC

Get paginated visible text from the single agent browser.

Inputs: offset, selector, max_chars, session_id. Returns: result

browser_list_tabsB

List tabs in the agent browser and identify the active tab.

Inputs: session_id. Returns: result

browser_navigateC

Navigate and return no, compact, or full snapshot observation.

Inputs: url (required), observe, session_id, timeout_ms, +1 more. Returns: result

browser_reloadC

Reload and return no, compact, or full snapshot observation.

Inputs: observe, session_id, timeout_ms. Returns: result

browser_screenshotC

Capture the single agent browser; session_id is usually omitted.

Inputs: quality, full_page, session_id, image_format.

browser_select_option_refC

Select an option by snapshot ref and return the updated snapshot.

Inputs: ref (required), value (required), observe, session_id, +1 more. Returns: result

browser_set_form_valuesC

Fill several snapshot refs in one call; each item has ref and value.

Inputs: fields (required), observe, session_id, timeout_ms. Returns: result

browser_set_value_refC

Fill a snapshot ref without echoing the value into the tool result.

Inputs: ref (required), value (required), observe, session_id, +1 more. Returns: result

browser_snapshotC

Return a page snapshot and optionally match controls by query and role.

Inputs: role, query, session_id, max_results, +1 more. Returns: result

browser_startB

Start the agent browser; proxy and geo settings come from server config.

Inputs: seed, headless, humanize, fingerprint_profile. Returns: result

browser_statusA

Return status for the single agent browser; session_id is usually omitted.

Inputs: session_id. Returns: result

browser_stopB

Close the single agent browser; session_id is usually omitted.

Inputs: session_id. Returns: result

browser_type_text_refC

Type into a snapshot ref without echoing the text into the result.

Inputs: ref (required), text (required), observe, session_id, +1 more. Returns: result

browser_wait_forA

Wait until all supplied text, URL, and ref-state conditions are true.

text and url use case-insensitive substring matching. state is applied only when ref is supplied. At least one condition is required.

Inputs: ref, url, text, state, +2 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools map to a clearly distinct action on the browser or binary. Minor overlap exists among content-extraction tools (browser_snapshot, browser_get_text, browser_find_text) and among input tools (browser_set_value_ref, browser_type_text_ref, browser_set_form_values), but descriptions differentiate them well enough that misselection is unlikely.

    Naming Consistency4/5

    The set is dominated by a consistent browser_verb_noun pattern, with action-oriented suffixes (click_ref, set_value_ref). The only deviation is the two binary_* tools, which themselves share a coherent verb_noun pattern, so the naming remains predictable overall.

    Tool Count4/5

    19 tools is slightly heavy but justified by genuine browser-automation breadth (lifecycle, tabs, navigation, interaction, extraction, waiting) plus binary management. Almost every tool covers a distinct capability, with little redundancy.

    Completeness4/5

    Core lifecycle (start/stop/status/reload/navigate), tab handling, form interaction, content extraction, waiting, and binary install/verify are covered, giving a nearly complete surface. Gaps remain for close-tab, keyboard/hover/scroll or drag actions, and cookie/download control, but agents can largely work around these.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      Not graded
      maintenance
      A MCP server that provides browser automation tools, allowing users to navigate websites, take screenshots, click elements, fill forms, and execute JavaScript through Playwright.
      8
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI-powered browser automation, web scraping, and testing using Playwright across Chromium, Firefox, and WebKit. It allows users to perform actions like navigation, clicking, typing, and taking screenshots through natural language interfaces.
      24 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that enables AI agents to automate browser interactions using Playwright and Cloudflare Workers, supporting tasks like navigation, clicking, typing, and screenshots.
      Apache 2.0