Skip to main content
Glama

camoufox-agent

Servidor MCP de automatización de navegador sobre el navegador oficial Camoufox (binario fijado por SHA-256, sin compilar Firefox). Basado en el proyecto MIT whit3rabbit/camoufox-mcp. README original: docs/upstream-README.md.

Dos modos en un solo binario:

Comando

Qué hace

camoufox-agent

Servidor MCP por stdio (Claude Code, opencode, Hermes, OpenClaw, Codex, Cursor…)

camoufox-agent serve

HTTP: REST para apps web, MCP Streamable HTTP en /mcp, vista en vivo en /live, cron

camoufox-agent run <flujo>

Ejecuta un flujo guardado una vez (para cron/launchd/Programador de tareas)

camoufox-agent test <flujo…> | --all [--junit f.xml]

Ejecuta flujos como pruebas; exit 1 si alguna falla

camoufox-agent secret set <nombre> / secret list

Credenciales para fillSecret

camoufox-agent fetch / doctor

Descarga del navegador / diagnóstico

Instalación

Publicado en npm: camoufox-agent (Node >= 22).

npm i -g camoufox-agent
camoufox-agent fetch      # descarga el navegador fijado por SHA-256 (Linux, macOS, Windows)
camoufox-agent doctor     # verifica pines, navegador y un lanzamiento real

Sin instalar globalmente: npx -y camoufox-agent <comando> (la primera vez ejecute npx -y camoufox-agent fetch).

Registro en agentes

Agente

Comando / configuración

Claude Code

claude mcp add camoufox -- camoufox-agent (o -- npx -y camoufox-agent)

Codex

codex mcp add camoufox -- camoufox-agent

opencode

opencode.json: "mcp": { "camoufox-agent": { "type": "local", "command": ["camoufox-agent"], "enabled": true } }

Hermes

printf "Y\n" | hermes mcp add camoufox-agent --command camoufox-agent

OpenClaw

openclaw mcp add camoufox-agent --command camoufox-agent

Por HTTP

camoufox-agent serve y apunte el cliente a http://127.0.0.1:9420/mcp con Authorization: Bearer <token>

Si el agente no hereda su PATH, use la ruta absoluta del binario (which camoufox-agent).

Desde el código fuente

git clone https://github.com/Jul879n/camoufox-agent && cd camoufox-agent
npm install --include=optional && npm run build
npm link
camoufox-agent fetch

Related MCP server: CamoFox MCP

Novedades respecto al upstream

  • Sesiones sin límite de tiempo (CAMOUFOX_MCP_SESSION_TTL_MS sin definir = nunca expiran). CAMOUFOX_MCP_MAX_SESSIONS (4 por defecto, máx. 64), CAMOUFOX_MCP_MAX_CONCURRENCY (4), CAMOUFOX_MCP_MAX_SEQUENCE_ACTIONS (100).

  • Perfiles persistentes: browse_session_start { profile } guarda cookies, localStorage e IndexedDB (browse_profiles_list, browse_profile_delete). El perfil fija os/locale/proxy/window/fingerprint.

  • Credenciales sin exponerlas: acción fillSecret (CAMOUFOX_SECRET_<NOMBRE> o secrets.json con chmod 600).

  • Archivos: acciones upload y download (por selector o por url, esta última recomendada para archivos grandes; timeout hasta 1 h) dentro de CAMOUFOX_MCP_FILES_DIR (por defecto <HOME>/files).

  • Extracción estructurada: browse_extract (paginación, saveAs JSON/CSV en exports/).

  • Flujos: flow_save, flow_list, flow_run; login por script, extracción y schedule (cron de 5 campos).

  • Humano en el loop: acciones waitForHuman y promptCode; con serve, el usuario interviene desde /live. Para recibir un aviso cuando una sesión espera a una persona: CAMOUFOX_AGENT_NOTIFY_URL (webhook), CAMOUFOX_AGENT_NOTIFY_SECRET (firma HMAC X-Webhook-Signature-V2) y CAMOUFOX_AGENT_PUBLIC_URL (base del enlace /live, sin token). CAMOUFOX_AGENT_NOTIFY_URL admite varias URLs separadas por coma y cada una recibe su propio enlace /live?ott=… de un solo uso (15 min; también la herramienta live_link). Los flows con schedule esperan hasta 10 min; los lanzados por tool/HTTP/CLI devuelven needs_human al instante.

  • Acción goto dentro de secuencias y sesiones.

  • Diagnóstico para desarrollo:

    • browse_diagnose (url o sessionId): consola y errores no capturados con stack, red (tiempos, tamaños, fallos, caché, compresión), Web Vitals y navigation timing, estadísticas del DOM y una auditoría (SEO, accesibilidad, cabeceras de seguridad, cookies, contenido mixto). saveAs guarda el informe en exports/.

    • browse_inspect: caja, estilos computados, reglas CSS aplicadas, visibilidad, desbordamiento y árbol de accesibilidad de un selector.

    • emulation en cualquier tool: colorScheme, reducedMotion, timezoneId, geolocation, offline.

    • browse_session_start { recordHar } (HAR al cerrar) y browse_session_trace (trace de Playwright en .zip).

    • Límite: Camoufox es Firefox, sin CDP (detalle y equivalentes en «Depurar y probar apps»). Faltan CLS y long tasks nativos; tbtApproxMs los aproxima.

  • Depuración y pruebas (0.3.0): ver Depurar y probar apps.

Datos en CAMOUFOX_AGENT_HOME (por defecto ~/.camoufox-agent): profiles/, flows/, runs/, files/, secrets.json.

Depurar y probar apps

Camoufox es Firefox (Juggler, sin CDP): no hay heap, profiler, cobertura JS ni throttling de CPU. Cada función de chrome-devtools-mcp tiene aquí un equivalente que sí funciona en Firefox:

chrome-devtools-mcp

camoufox-agent

lighthouse_audit

browse_audit: axe-core (accesibilidad), SEO, buenas prácticas, seguridad y puntaje de rendimiento con la fórmula de Lighthouse sobre métricas de Firefox (sin CLS; TBT y Speed Index aproximados). Comparable entre corridas de camoufox-agent, no idéntico al de Chrome

take_heapsnapshot

browse_profile_app { mode: "leaks" }: repite una acción N veces y mide el crecimiento de nodos DOM, listeners y timers

cobertura

browse_profile_app { mode: "cssCoverage" } (reglas CSS que nunca aplicaron). Sin cobertura JS

performance_start_trace

browse_session_trace (trace de Playwright), browse_diagnose (cascada de recursos, tbtApproxMs y longFrames, presupuestos con budgets)

emulate (red)

network en cualquier tool y browse_session_network: latencia, bloqueos, mocks y offline

emulate (móvil)

emulation.device (iphone-15, pixel-8, ipad, laptop-720p, desktop-1080p), hasTouch, forcedColors, contrast, javaScriptEnabled, httpCredentials

list_network_requests / get_network_request

browse_diagnose + browse_network_request { id } (cabeceras, cuerpo, tiempos)

list_pages / select_page / handle_dialog

browse_session_tabs y la acción dialog

drag, fill_form, click…

acciones drag, fill, click…

Pérdidas reales sin Chrome: throttling de CPU, user agent móvil (isMobile no existe en Firefox y cambiar el user agent rompería la huella) y ver cómo renderiza Chrome. Camoufox tampoco genera video (recordVideo no produce archivo) y fija navigator.maxTouchPoints en 0 aunque hasTouch esté activo (siguen funcionando ontouchstart y pointer: coarse).

Además, lo que chrome-devtools-mcp no tiene:

  • Aserciones expect (visible, text, value, count, url, noConsoleErrors, noFailedRequests…) con reintento, soft y la acción clearDiagnostics.

  • Flujos como pruebas: flow_run marca cada paso passed|failed|error, guarda una captura -fail.png y el contexto de la falla; camoufox-agent test <flujo…> | --all [--junit archivo.xml] sale con 1 si algo falla.

  • Mocks de red, frames de WebSocket (browse_diagnose → network.websockets), storage (browse_storage), regresión visual (browse_visual_diff) y presupuestos de rendimiento.

// Auditoría móvil con informe HTML
browse_audit { "url": "http://localhost:3000/app", "formFactor": "mobile", "saveAs": "audit.html" }

// Probar que +1 sube el contador, con la API simulada y sin errores de consola
browse_session_network { "sessionId": "…", "network": { "mocks": [{ "url": "**/api/data", "status": 500 }] } }
browse_session_action { "sessionId": "…", "action": { "type": "click", "selector": "#inc" } }
browse_session_action { "sessionId": "…", "action": { "type": "expect", "check": "text", "selector": "#count", "equals": "1" } }

// Fugas al repetir una acción
browse_profile_app { "sessionId": "…", "mode": "leaks", "actions": [{ "type": "click", "selector": "#open" }, { "type": "click", "selector": "#close" }], "iterations": 10 }

// Línea base visual y comparación
browse_visual_diff { "sessionId": "…", "name": "home", "maxDiffPct": 0.5 }

Servidor HTTP (serve)

CAMOUFOX_AGENT_TOKEN=secreto camoufox-agent serve --port 9420
  • GET /health (sin auth) · GET /api/tools · POST /api/tools/:nombre (mismo cuerpo que el input de la tool MCP; 400 invalid_input, 404 unknown_tool, 422 si la tool devuelve error).

  • POST|GET|DELETE /mcp: MCP Streamable HTTP.

  • GET /live?token=…: vista en vivo (capturas JPEG cada 700 ms, clics y teclado reenviados, pendientes «Listo»/código).

  • GET /api/sessions, /api/sessions/:id/frame.jpg, POST /api/sessions/:id/input, GET /api/human, POST /api/human/:id, GET /api/flows/:nombre/runs.

  • Auth: CAMOUFOX_AGENT_TOKEN (obligatorio si --host no es loopback). CORS: CAMOUFOX_AGENT_CORS_ORIGINS=https://app.ejemplo.cl.

  • Otras: CAMOUFOX_AGENT_HOST, CAMOUFOX_AGENT_PORT, CAMOUFOX_AGENT_HEADLESS (true|false|virtual).

Desde una app web, llame al servidor desde su backend; el token nunca debe llegar al navegador del cliente:

const res = await fetch("http://127.0.0.1:9420/api/tools/browse_extract", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CAMOUFOX_AGENT_TOKEN}`, "content-type": "application/json" },
  body: JSON.stringify({ url: "https://quotes.toscrape.com", itemSelector: ".quote", fields: { author: { selector: ".author" } }, maxPages: 2 }),
});

Automatizaciones agendadas

Con serve, cada flujo con schedule se ejecuta solo (protect: no se solapa consigo mismo). Sin servidor, programe camoufox-agent run <flujo>:

  • Linux: */30 * * * * camoufox-agent run mi-flujo >> ~/camoufox.log 2>&1

  • macOS: plist de launchd con ProgramArguments = [/usr/local/bin/camoufox-agent, run, mi-flujo] y StartInterval.

  • Windows: schtasks /create /tn camoufox-mi-flujo /sc daily /st 08:00 /tr "camoufox-agent run mi-flujo"

Docker Compose

CAMOUFOX_AGENT_TOKEN=secreto docker compose up -d --build
curl -s 127.0.0.1:9420/health

Los datos quedan en ./data (el contenedor corre con uid 1001: chown 1001 data en Linux).

Pruebas

npm run lint && npm run test:unit
for s in upload profile extract diagnose diagnose-session expect flow-test tabs-dialogs drag network emulation storage perf audit profile-app visual; do node scripts/mcp-smoke.mjs $s; done
CAMOUFOX_SECRET_HEROKU_PASS='SuperSecretPassword!' node scripts/mcp-smoke.mjs secret
CAMOUFOX_SECRET_HEROKU_PASS='SuperSecretPassword!' node scripts/mcp-smoke.mjs flow

Los escenarios usan un sitio local (tests/fixtures/site.mjs) con CAMOUFOX_MCP_ALLOWED_PRIVATE_HOSTS=localhost.

Available Tools

26 tools
browseC
Read-only

Navigate once and return bounded page content.

Inputs: url (required), os, args, geoip, +25 more. Returns: url, html, text, title, +20 more

browse_consoleB
Read-only

Navigate once and return bounded console diagnostics.

Inputs: url (required), os, args, geoip, +20 more. Returns: url, title, status, console, +14 more

browse_diagnoseA

Developer diagnostics for a page or session: console and uncaught errors with stacks, network timings/sizes/failures/caching, Web Vitals and navigation timing, DOM stats, and an audit (SEO, accessibility, security headers, cookies, mixed content). Supports emulation (color scheme, timezone, geolocation, offline). Firefox has no Lighthouse/CDP profiling.

Inputs: os, url, args, geoip, +26 more. Returns: object

browse_extractA

Extract repeated items (rows/cards) into structured JSON, optionally paginating and saving to JSON/CSV under CAMOUFOX_MCP_FILES_DIR/exports. Use url (one-shot) or sessionId.

Inputs: fields (required), itemSelector (required), os, url, +28 more. Returns: url, rows, count, pages, +3 more

browse_findB
Read-only

Navigate once, search visible text, and return bounded context matches.

Inputs: url (required), query (required), os, args, +24 more. Returns: url, query, title, status, +19 more

browse_formsC
Read-only

Navigate once and return form fields and submit controls.

Inputs: url (required), os, args, geoip, +23 more. Returns: url, forms, title, status, +18 more

browse_inspectA
Read-only

Inspect one element like DevTools: box model, computed styles, matched CSS rules, attributes, visibility, overflow, accessibility tree.

Inputs: selector (required), os, url, args, +25 more. Returns: object

browse_network_summaryC
Read-only

Navigate once and return a bounded network diagnostic summary.

Inputs: url (required), os, args, geoip, +21 more. Returns: url, title, failed, status, +18 more

browse_outlineC
Read-only

Navigate once and return page headings and landmarks.

Inputs: url (required), os, args, geoip, +22 more. Returns: url, title, status, message, +19 more

browse_profile_deleteB
DestructiveIdempotent

Delete a named browser profile and its saved logins.

Inputs: name (required). Returns: name, deleted

browse_profiles_listA
Read-onlyIdempotent

List named persistent browser profiles.

Inputs: no named parameters. Returns: profiles

browse_screenshotC
Read-only

Navigate once and capture a bounded screenshot.

Inputs: url (required), os, args, type, +24 more. Returns: url, title, status, message, +12 more

browse_sequenceB

Navigate once, run bounded selector actions, then return final state.

Inputs: url (required), actions (required), os, args, +27 more. Returns: url, html, text, title, +23 more

browse_session_actionC

Run one bounded action in an existing browser session.

Inputs: action (required), sessionId (required), maxChars, selector, +2 more. Returns: action, message, snapshot, expiresAt, +11 more

browse_session_closeB

Close an existing browser session.

Inputs: sessionId (required). Returns: closed, sessionId

browse_session_navigateC

Navigate an existing browser session.

Inputs: url (required), sessionId (required), timeout, maxChars, +4 more. Returns: url, html, text, title, +21 more

browse_session_resumeA

Resume a paused session after human action and return current state.

Inputs: sessionId (required), timeout, maxChars, selector, +3 more. Returns: url, text, title, status, +25 more

browse_session_snapshotC
Read-only

Read the current state of an existing browser session.

Inputs: sessionId (required), maxChars, selector, maxElements, +1 more. Returns: url, text, title, status, +25 more

browse_session_startB

Start an isolated short-lived browser session.

Inputs: os, args, geoip, proxy, +21 more. Returns: browser, expiresAt, sessionId, selectedOS, +3 more

browse_session_traceA

Start or stop a Playwright trace (screenshots, DOM snapshots, network) for a session and save it as a .zip under exports/.

Inputs: action (required), sessionId (required), saveAs. Returns: object

browse_snapshotC
Read-only

Navigate once and return visible text, ARIA snapshot, and interactive metadata.

Inputs: url (required), os, args, geoip, +23 more. Returns: url, text, title, status, +23 more

camoufox_statusA
Read-onlyIdempotent

Return server, browser, queue, session, and policy status without launching a page.

Inputs: no named parameters. Returns: browser, version, maxQueue, platform, +14 more

flow_listA
Read-onlyIdempotent

List saved flows (scripted login/automation) with their schedule and last run.

Inputs: no named parameters. Returns: flows

flow_runA

Run a saved flow now and return its result (also stored under runs/).

Inputs: name (required). Returns: ok, name, error, steps, +5 more

flow_saveA
Idempotent

Create or overwrite a saved flow: optional profile, startUrl, bounded actions, optional extract and cron schedule.

Inputs: flow (required), name (required). Returns: name, saved

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 26 tools

    Disambiguation3/5

    The 13 one-shot browse_* tools each return a different facet, but several overlap heavily: browse vs browse_snapshot vs browse_extract, browse_console vs browse_diagnose, and browse_network_summary vs browse_diagnose. The descriptions help, but an agent must carefully choose among many similar navigate-once variants.

    Naming Consistency4/5

    Most tools follow a consistent browse_<facet> or browse_session_<action> pattern, and flow_* tools are coherent within their domain. Minor deviations exist, such as browse_profiles_list vs browse_profile_delete and the unprefixed camoufox_status.

    Tool Count3/5

    At 26 tools, the surface is heavy and many one-shot browse variants could be consolidated behind a mode parameter. Each tool has a plausible purpose, but the count is borderline excessive for the apparent scope.

    Completeness4/5

    Core browser automation workflows are well covered: navigation, sessions, interaction, extraction, diagnostics, screenshots, profiles, and saved flows. Minor gaps remain, such as flow deletion, explicit profile creation, and session listing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to automate a privacy-focused Firefox-based browser through MCP, with session and profile management, navigation, interaction, extraction, screenshots, JavaScript execution, tabs, downloads, and permission/URL validation.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Gives MCP-compatible AI agents an anti-detection browser toolset for navigating, interacting with, searching, and extracting content from websites, plus downloads, multi-tab workflows, and persistent sessions with cookies and saved profiles. It enables reliable automation of the web without getting blocked by running against a separate Camoufox-based browser server.
      581 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Exposes a 47-tool browser automation surface to MCP clients, enabling AI agents to navigate, interact with, observe, and extract content from web pages across multi-tab sessions. Runs on Camoufox-based anti-detection behavior so agents can automate sites that block conventional headless browsers, with session persistence, cookie import, and stdio or HTTP transport.
      581 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and human operators to drive isolated, persistent browser profiles with their own cookies, fingerprints, and proxies. Exposes tools for profile lifecycle, navigation, clicking, typing, extraction, screenshots, JavaScript evaluation, tabs, cookies, and waits over a local MCP endpoint.
      -