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

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:

• Hermes Agent
• OpenClaw
• Claude Desktop, Cursor, and OpenCode

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

• Tools and profiles
• Configuration and environment variables
• Fingerprint profiles and geo behavior
• Security and operational safeguards
• Development and testing

License

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