camoufox-agent
camoufox-agent is an MCP server that drives the stealth Camoufox (Firefox) browser for scraping, automation, testing, and diagnostics.
One-shot browsing:
browse,browse_snapshot,browse_links,browse_forms,browse_outline,browse_find,browse_screenshot,browse_console,browse_network_summary— navigate once and return bounded text/HTML/ARIA/links/forms/headings/matches/screenshots/console/network.Action sequences:
browse_sequenceruns bounded actions (click, hover, fill, type, select, press, waitFor, scroll, upload, download, fillSecret, goto, waitForHuman, promptCode, evaluate) after navigation.Persistent sessions:
browse_session_start/navigate/action/snapshot/resume/closefor multi-step work, with optional named profiles (cookies, localStorage, IndexedDB), HAR recording, and Playwright traces.Structured extraction:
browse_extractpulls repeated items into JSON/CSV with pagination andsaveAs.Saved flows & scheduling:
flow_save,flow_list,flow_runfor scripted logins/automation with cron schedules and per-step pass/fail results.Developer diagnostics:
browse_diagnose(console, network, Web Vitals, DOM stats, SEO/a11y/security audit),browse_inspect(box model, computed styles, CSS rules, a11y tree),browse_session_trace.Stealth & emulation: OS/locale/proxy/geoip spoofing, humanize, stealth profiles, viewport/window, color scheme, timezone, geolocation, offline, device emulation, block WebGL/images/WebRTC.
CAPTCHA handling:
captchaPolicy(detect/pause/fail/attempt) with challenge metadata, playbooks, and human-in-the-loop actions.Profile management:
browse_profiles_list,browse_profile_delete.Server status:
camoufox_statusreports version, browser availability, sessions, queue, and security policy.Safety controls: unsafe options (args, addons, Firefox prefs) gated behind
CAMOUFOX_MCP_ALLOW_UNSAFE_OPTIONS, SSRF/local-network URL policy, secrets never returned.
Enables Firefox-based browser automation through the Camoufox browser, providing tools for navigation, content extraction, form interaction, screenshots, diagnostics, persistent sessions, and scripted flows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@camoufox-agent Go to news.ycombinator.com and list the top 10 headlines."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Servidor MCP por stdio (Claude Code, opencode, Hermes, OpenClaw, Codex, Cursor…) |
| HTTP: REST para apps web, MCP Streamable HTTP en |
| Ejecuta un flujo guardado una vez (para cron/launchd/Programador de tareas) |
| Ejecuta flujos como pruebas; exit 1 si alguna falla |
| Credenciales para |
| 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 realSin 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 |
|
Codex |
|
opencode |
|
Hermes |
|
OpenClaw |
|
Por HTTP |
|
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 fetchRelated MCP server: CamoFox MCP
Novedades respecto al upstream
Sesiones sin límite de tiempo (
CAMOUFOX_MCP_SESSION_TTL_MSsin 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 fijaos/locale/proxy/window/fingerprint.Credenciales sin exponerlas: acción
fillSecret(CAMOUFOX_SECRET_<NOMBRE>osecrets.jsoncon chmod 600).Archivos: acciones
uploadydownload(porselectoro porurl, esta última recomendada para archivos grandes;timeouthasta 1 h) dentro deCAMOUFOX_MCP_FILES_DIR(por defecto<HOME>/files).Extracción estructurada:
browse_extract(paginación,saveAsJSON/CSV enexports/).Flujos:
flow_save,flow_list,flow_run; login por script, extracción yschedule(cron de 5 campos).Humano en el loop: acciones
waitForHumanypromptCode; conserve, 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 HMACX-Webhook-Signature-V2) yCAMOUFOX_AGENT_PUBLIC_URL(base del enlace/live, sin token).CAMOUFOX_AGENT_NOTIFY_URLadmite varias URLs separadas por coma y cada una recibe su propio enlace/live?ott=…de un solo uso (15 min; también la herramientalive_link). Los flows conscheduleesperan hasta 10 min; los lanzados por tool/HTTP/CLI devuelvenneeds_humanal instante.Acción
gotodentro de secuencias y sesiones.Diagnóstico para desarrollo:
browse_diagnose(urlosessionId): 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).saveAsguarda el informe enexports/.browse_inspect: caja, estilos computados, reglas CSS aplicadas, visibilidad, desbordamiento y árbol de accesibilidad de un selector.emulationen cualquier tool:colorScheme,reducedMotion,timezoneId,geolocation,offline.browse_session_start { recordHar }(HAR al cerrar) ybrowse_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;
tbtApproxMslos 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:
| camoufox-agent |
|
|
|
|
cobertura |
|
|
|
|
|
|
|
|
|
|
|
| acciones |
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,softy la acciónclearDiagnostics.Flujos como pruebas:
flow_runmarca cada pasopassed|failed|error, guarda una captura-fail.pngy 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 9420GET /health(sin auth) ·GET /api/tools·POST /api/tools/:nombre(mismo cuerpo que el input de la tool MCP; 400invalid_input, 404unknown_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--hostno 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>&1macOS: plist de
launchdconProgramArguments=[/usr/local/bin/camoufox-agent, run, mi-flujo]yStartInterval.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/healthLos 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 flowLos escenarios usan un sitio local (tests/fixtures/site.mjs) con CAMOUFOX_MCP_ALLOWED_PRIVATE_HOSTS=localhost.
Available Tools
26 toolsbrowseCRead-only
Navigate once and return bounded page content.
Inputs: url (required), os, args, geoip, +25 more. Returns: url, html, text, title, +20 more
browse_consoleBRead-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_findBRead-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_formsCRead-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_inspectARead-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_linksBRead-only
Navigate once and return only visible navigable links.
Inputs: url (required), os, args, geoip, +22 more. Returns: url, links, title, status, +17 more
browse_network_summaryCRead-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_outlineCRead-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_deleteBDestructiveIdempotent
Delete a named browser profile and its saved logins.
Inputs: name (required). Returns: name, deleted
browse_profiles_listARead-onlyIdempotent
List named persistent browser profiles.
Inputs: no named parameters. Returns: profiles
browse_screenshotCRead-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_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_snapshotCRead-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_snapshotCRead-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_statusARead-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_listARead-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_saveAIdempotent
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceGives 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceExposes 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 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-