camoufox-research
Camoufox Research
Kit de investigación en navegador para agentes de IA, expuesto a través de MCP.
Busca en la web. Lee páginas con mucho JavaScript. Interactúa con sitios web. Extrae datos. Supervisa cambios. Dale a tu agente de IA un navegador real.
AI Agent
│ (tools, resources, prompts)
▼
MCP
│
▼
Camoufox Research ← this server (48 tools)
│
▼
Camoufox ← anti-detect Firefox
│
▼
WebLa mayoría de los servidores MCP pueden leer la web. Este puede vivir en ella: abrir páginas, hacer clic, escribir, rellenar formularios, subir archivos, observar el tráfico de red, tomar capturas de pantalla etiquetadas, rastrear sitios completos, extraer tablas, supervisar cambios — y entregar todo eso a tu agente a través de MCP (stdio, HTTP o SSE).
¿Por qué Camoufox Research?
La mayoría de las herramientas de navegador MCP dan al agente acciones aisladas. Aquí el objetivo es diferente: un kit completo para investigación web — un servidor que tu agente puede usar de principio a fin.
🔎 Buscar — encuentra fuentes (DuckDuckGo mediante navegador anti-detección,
researchprofundo con más de 10 fuentes)🌐 Navegar — lee páginas JS/SPA, sesiones en vivo con pestañas, clics, formularios, subidas
👁️ Entender páginas — capturas etiquetadas (Set-of-Mark), árboles de instantáneas con referencias
📊 Extraer y exportar — campos por CSS/XPath, tablas → CSV, PDF/DOCX/XLSX, archivos JSON/Markdown
Related MCP server: camofox-browser-mcp
⚡ Demo de 30 segundos
"Encuentra todas las páginas de precios de este sitio web, extrae los precios y guárdalos en CSV."
Agent
├─ map_site discover every /pricing page
├─ crawl read them (cached)
├─ extract {"plan": "css:.plan", "price": "css:.price"}
└─ export format=csv → prices.csvSin código de automatización de navegador. Solo una frase para tu agente.
Qué hace (escenarios reales)
🔎 Investigación — "Encuentra información sobre este proyecto, revisa 10 fuentes y resume."
research→fetch_page→export
🕷 Rastreo — "Recorre todo el sitio y encuentra todas las páginas de documentación."
sitemap→crawl/map_site
📊 Extracción — "Recoge los precios de la tabla y guárdalos como CSV."
extract/table_extract→export
👁 Visión — "Mira la página, encuentra el botón Descargar y presiónalo."
screenshot(som=True)→snapshot→session_click(ref="4")
📡 Supervisión — "Revisa esta página y dime si ha cambiado."
fetch_page→page_diff(lectura delta ahorra tokens)
Un escenario completo (demo estrella)
git clone https://github.com/aidvizhhub/camoufox-research.git && cd camoufox-research
python3 -m venv ~/.venvs/camoufox-research
~/.venvs/camoufox-research/bin/pip install .
~/.venvs/camoufox-research/bin/python -m camoufox fetch # download browser (once)Luego pregunta a tu agente:
"Encuentra los artículos más recientes sobre Camoufox, compáralos y guarda el resultado en Markdown."
Agent
├─ web_search "camoufox browser"
├─ research 10+ sources, dedup
├─ fetch_page read the best articles
├─ extract title / date / key points per source
├─ page_diff skip unchanged pages
└─ export format=md → report.mdEse es el punto: tu agente maneja un navegador real, tú solo describes el objetivo.
¿Necesitas una herramienta? Empieza aquí
Lo que necesitas | Herramienta |
Encontrar información |
|
Leer una página (incluso JS/SPA) |
|
Leer muchas páginas a la vez |
|
Recorrer un sitio completo |
|
Obtener campos específicos (CSS o XPath) |
|
Tablas → CSV |
|
Hacer clic / escribir / pulsar teclas |
|
Entender la interfaz |
|
Rellenar un formulario en una llamada |
|
Subir un archivo |
|
Descargar un archivo |
|
Observar red / consola JS |
|
Seguimiento de cambios |
|
Leer PDF / DOCX / XLSX |
|
Fuentes RSS / sitemap |
|
Comprobar enlaces rotos |
|
Guardar resultados en disco |
|
Mantener sesiones iniciadas |
|
Cambiar proxy sobre la marcha |
|
Ver lo que hizo el servidor |
|
Visión — páginas con números

Screenshot snapshot agent
│ │ │
▼ ▼ ▼
┌──────────┐ - ref: 3 session_click(ref="3")
│ [1][2][3]│ - tag: a ───► browser clicks exact element
│ [4] [5] │ - text: "Download"
└──────────┘snapshot devuelve un árbol YAML compacto de elementos interactivos (~2–5 KB en lugar de
más de 100 KB de HTML) con un ref en cada uno. Haz clic por ref, sin selectores frágiles.
Inicio rápido
# 1. Install
git clone https://github.com/aidvizhhub/camoufox-research.git && cd camoufox-research
python3 -m venv ~/.venvs/camoufox-research
~/.venvs/camoufox-research/bin/pip install .
# 2. Download the browser (once)
~/.venvs/camoufox-research/bin/python -m camoufox fetchConéctate a tu cliente MCP (OpenCode / Claude Desktop / Cursor) — consulta Conectar a MCP.
Pide a tu agente que investigue un sitio web:
"Encuentra los artículos más recientes sobre Camoufox, compáralos y guarda el resultado en Markdown."
Instalación
git clone https://github.com/aidvizhhub/camoufox-research.git
cd camoufox-research
# 1. venv + package
python3 -m venv ~/.venvs/camoufox-research
~/.venvs/camoufox-research/bin/pip install .
# 2. download the browser (once)
~/.venvs/camoufox-research/bin/python -m camoufox fetch
# 3. smoke check (stdio server, waits on stdin)
~/.venvs/camoufox-research/bin/camoufox-researchWindows: venv\Scripts\pip.exe install ., venv\Scripts\python.exe -m camoufox fetch;
necesita Python de python.org (no de MS Store) y VC++ Redistributable.
Conectar a MCP
opencode (~/.config/opencode/opencode.json):
{
"mcp": {
"camoufox": {
"type": "local",
"command": ["/path/to/venv/bin/camoufox-research"],
"enabled": true
}
}
}Claude Desktop, Cursor y otros — ejemplos listos en mcp/config/.
No se necesita instalación: python mcp/server.py funciona desde los fuentes.
Comprueba: opencode mcp list → camoufox: connected.
Herramientas (48)
Grupo | Herramientas |
Investigación |
|
Lectura |
|
Estructura |
|
Datos |
|
Visión |
|
Navegador |
|
Sesión en vivo |
|
Red |
|
Archivos |
|
Observabilidad |
|
Config. de red |
|
Servicio |
|
Recursos y avisos MCP
Recursos (datos legibles "como archivos"):
camoufox://stats,camoufox://cache,camoufox://session,camoufox://infoAvisos (recetas listas):
research_plan,extract_schema,monitor_page
Transportes
stdio (predeterminado), http, sse:
camoufox-research --transport http --port 8833 # or env CAMOUFOX_PORTComportamiento
El navegador vive en un proceso de trabajo separado (síncrono, sin interfaz) — el servidor MCP stdio nunca se bloquea.
Las páginas JS/SPA se leen sin preparación: sondeo de contenido + desplazamiento + detección de estabilidad; vacío → reintento.
Caché: sqlite
~/.cache/camoufox-research/cache.db, TTL 24 h, reintento con retroceso;delta=Trueomite releer páginas sin cambios.Configuración solo mediante variables de entorno (ver
configs/example.env):CAMOUFOX_VENV,CAMOUFOX_CACHE_DIR, tiempos de espera, proxy.
Desarrollo
Ver CONTRIBUTING.md: estructura, cómo añadir una nueva herramienta, ritual de prueba de humo.
CI
GitHub Actions en cada push: instalación en Python 3.10/3.11/3.12, comprobación de importación,
prueba de humo MCP stdio (initialize → tools/list → ping). Las pruebas completas del navegador se ejecutan
localmente (scripts/update_camoufox.py + prueba de humo manual).
Diario de experiencia
EXPERIENCE.md — lecciones verificadas y minas ("en qué no pisar"): errores de asyncio/serve, 403-vs-urllib, Playwright no seguro para hilos, límites de XPath de ElementTree, y más.
Licencias de dependencias
camoufox — ver su repositorio
mcp — MIT
trafilatura — GPL-3.0 (opcional: extracción de texto)
Available Tools
18 toolsbatch_fetchПакетное чтениеARead-onlyIdempotent
Открывает НЕСКОЛЬКО URL в одном браузере — для глубокого ресёрча на 30-50 источников одним вызовом вместо серии холодных стартов. Кэш: уже посещённые URL возвращаются мгновенно, без браузера. Rate limit между переходами защищает от капчи. Батч ≥8 URL — параллельно (пул потоков, свой браузер на поток); число воркеров автоопределяется по ресурсам машины (слабый ПК — 1-2, мощный — 3-4), max_parallel — явное ограничение. Возвращает тексты с разделителями '--- URL: ...'. article_only=True — извлечь текст статьи (Trafilatura), без меню и баннеров. Пример: batch_fetch(urls=["https://docs.python.org/3/", "https://opencode.ai/docs/"], max_chars=20000, article_only=True) ХОЧУ ПОЛНОТУ → max_chars=20000..100000 + article_only=True + max_parallel=4; экономия контекста → max_chars=4000 при 30+ URL. Замер 21.09 (8 URL разных доменов, холодный кэш): 4000 → 32 598 симв. за 36.4с (все 8 обрезаны ровно по 4000), 12000 → 96 598 симв. за 30.3с, 20000 → 154 449 симв. за 45.9с — время НЕ растёт от объёма: страница и так читается до потолка кэша (100k), max_chars режет только ОТВЕТ. КОГДА: читать 10-50 URL одним вызовом (глубокий ресёрч после research(queries=[...]) или crawl/map_site). НЕ КОГДА: 1-2 страницы → fetch_page; URL ещё не собраны → research, sitemap, map_site сначала.
Inputs: urls (required), max_chars, article_only, max_parallel. Returns: result
check_linksПроверка ссылокARead-onlyIdempotent
КОГДА: перед публикацией или после редизайна — найти битые ссылки на странице. ЧТО: HTTP-статусы собранных ссылок, отчёт вида «[404] URL». timeout — срок НА КАЖДУЮ ссылку (15с). Обычный путь (urllib) идёт ОГРАНИЧЕННЫМ ПУЛОМ потоков: CAMOUFOX_LINK_WORKERS (дефолт 8, потолок 16) — 50 ссылок ≈ минута, а не ~12. НО при поднятом живом браузере (serve) запросы идут через его sync-Playwright — он потокопривязан, поэтому пул принудительно 1 (последовательно). Бюджет вызова мост поднимает сам (900с) — таймаут MCP-клиента ставь ≥900с. НЕ: жди параллельности, когда поднят живой браузер — там строго по одной (грабли: 4 потока → 15/15 error); внешние ссылки → internal_only=False.
Inputs: url (required), timeout, max_links, internal_only. Returns: result
crawlОбход сайтаARead-onlyIdempotent
КОГДА: собрать содержимое САЙТА целиком (BFS по внутренним ссылкам) для синтеза, а не одну страницу. ЧТО: тексты страниц (depth ≤ max_depth, всего ≤ max_pages) с разделителями '--- URL:'; кэш делает повторный обход дешёвым. Идёт долго (десятки переходов) — таймаут MCP-клиента ставь ≥900с. НЕ: нужны только URL → map_site / sitemap; сайт огромный → sitemap + pattern и уже потом crawl нужного раздела; одна страница → fetch_page.
Inputs: url (required), pattern, max_chars, max_depth, +2 more. Returns: result
exportЭкспорт результатаADestructive
КОГДА: результат нужен файлом на диске — CSV для таблиц, JSON для автоматизации, MD для отчёта. ЧТО: файл (json/csv/md) по своему path или авто в ~/.cache/camoufox-research/exports/. НЕ: результат идёт в разговор и синтез → отдай текст как есть.
Inputs: data (required), path, format. Returns: result
extractИзвлечение полейARead-onlyIdempotent
КОГДА: нужны конкретные поля страницы — при стабильной вёрстке селекторами (CSS/XPath) или из текста через llm=True, когда вёрстка хрупкая и селекторы отваливаются. ЧТО: schema — JSON-объект (можно строкой для совместимости): {"поле": "css:.price"} или {"поле": {"selector": ".price", "attr": "text|href|src"}}; llm=True — {"поле": "подсказка"} и нужен LLM (DeepSeek/Ollama), иначе честный ответ «недоступен». НЕ: нужен сплошной текст → fetch_page / batch_fetch; таблицы → table_extract; не знаешь селектор → сначала snapshot.
Inputs: url (required), schema (required), llm. Returns: result
extract_linksСсылки страницыBRead-onlyIdempotent
Собирает ссылки страницы (фильтр по подстроке pattern).
Inputs: url (required), pattern, max_links. Returns: result
fetch_pageЧтение страницыARead-onlyIdempotent
Текст страницы без HTML-мусора (статьи, доки, README). Кэш на сутки. article_only=True — текст статьи (Trafilatura), fallback — весь body. delta=True — delta-чтение: если контент не изменился с прошлого раза, вернёт маркер '[delta: ...]' вместо текста (не тратим токены на повтор). max_chars режет только ОТВЕТ, а не чтение: страница кладётся в кэш целиком (потолок 100k), поэтому повтор с большим max_chars мгновенный и бесплатный по времени (замер 21.09: asyncio-task.html = 46 094 симв. в кэше; 12000 = 26% текста, 40000 = 87%, все ответы 0.0с). КОГДА: прочитать 1 страницу (JS/SPA — тоже) чистым текстом. НЕ КОГДА: страниц 10+ → batch_fetch; нужны поля по схеме → extract; повторное чтение → delta=True; нужен клик/ввод → session_start.
Inputs: url (required), delta, max_chars, article_only. Returns: result
map_siteКарта сайтаARead-onlyIdempotent
КОГДА: понять структуру сайта — какие разделы и страницы есть, без чтения содержимого. ЧТО: ссылки того же домена со стартовой страницы (до max_links), pattern — фильтр по URL. НЕ: нужны тексты → crawl; есть sitemap.xml → sitemap (полнее и дешевле); одна страница → fetch_page.
Inputs: url (required), pattern, max_links. Returns: result
page_diffДифф страницыARead-onlyIdempotent
КОГДА: страницу уже читали, и нужно узнать, что ИЗМЕНИЛОСЬ — цены, доки, новости (мониторинг, второй и далее заходы). ЧТО: дифф свежего чтения с прошлым из кэша, «что поменялось». НЕ: страница читается впервые — сравнивать не с чем, сначала fetch_page; нужна полная текстовая версия → fetch_page.
Inputs: url (required), max_chars. Returns: result
paper_searchПоиск статейARead-onlyIdempotent
Поиск научных статей: arXiv + Semantic Scholar (бесплатные API, без ключей). Возвращает статьи с годом/авторами/цитатами — первоисточники (tier 0), которых общий поиск почти не видит (паттерн индустрии: vertical index / arxiv-канал рядом с вебом). Кэш на сутки. sources — какие индексы брать (arxiv/semantic/ crossref/wiki); пусто — arxiv+semantic. Пример: paper_search("deep research agents", sources=["arxiv"])
Inputs: query (required), sources, max_results. Returns: result
pingПроверка связиARead-onlyIdempotent
Проверка связи: возвращает pong.
Это ПРИКЛАДНОЙ health-тул, а не протокольный ping (его в спеке
2026-07-28 убрали). Имя оставлено публичным контрактом — менять нельзя.
Inputs: no named parameters. Returns: result
read_documentЧтение документаARead-onlyIdempotent
КОГДА: нужен документ (PDF/DOCX/XLSX) — отчёт, прайс, спецификация; такие файлы часто попадаются ссылками с сайтов. ЧТО: текст документа; source — URL или локальный путь (pypdf / python-docx / openpyxl, до max_chars). Локальный путь — только из каталога загрузок сервера (туда кладёт session_download); свой путь — вентиль CAMOUFOX_ALLOW_ANY_PATH=1. НЕ: HTML-страница → fetch_page (дешевле); старые .doc/.xls не читаются — сначала libreoffice --convert-to docx/xlsx.
Inputs: source (required), max_chars. Returns: result
researchГлубокий ресёрчARead-onlyIdempotent
Когда: нужно СЕЙЧАС 10+ источников на тему одним вызовом — глубокий разбор без фонового ожидания. Один факт, новость или точный URL — это web_search. Что: сервер ищет по КАЖДОЙ формулировке (queries), дедуплицирует URL и отдаёт список со сниппетами; fetch_top>0 сразу читает топ-N текстов. Результат кэшируется на сутки.
По умолчанию хватит queries (2-4 формулировки) и fetch_top=3..5. Остальное — тонкая настройка, всё рабочее, но трогать не обязательно: max_chars режет только ответ; max_parallel — воркеры чтения; target_domains=N — цель по РАЗНЫМ доменам (20 = двадцать сайтов, доборка волнами); domains_limit=K — не больше K с одного домена; expand=True — переформулировки («X comparison», «X documentation»); terms_wave=True — вторая волна из редких термов первой (паттерн Open Deep Research); quality_first=True — доки/GitHub/arXiv первыми; fetch_all=True — тексты ВСЕХ отобранных, а не топ-N (30 источников × 12k ≈ 90k токенов); as_json=True — машинный JSON: meta (счётчики, follow-up запросы), sources (title/url/domain/tier/tier_label/snippet), texts, notes (тот же объект в structuredContent, content — прежняя строка); academic=True — вертикальный arXiv + Semantic Scholar канал (tier 0, без ключей); llm_planner=True — LLM-планировщик follow-up (DeepSeek/Ollama, нужен DEEPSEEK_API_KEY или OLLAMA_HOST, иначе пропуск); mode="быстро"|"полно"|"глубоко" (fast/full/deep) — пресет одним словом, трогает только ручки на дефолте (явный аргумент сильнее пресета). Пример глубокого разбора: research(queries=["deep research agents"], target_domains=20, domains_limit=2, expand=True, terms_wave=True, quality_first=True, academic=True, llm_planner=True, fetch_all=True, as_json=True, max_results_per_query=6).
Замер 21.09 (5 источников): fetch_top=0 — 0 текстов и 2 822 симв. за 5.5с; fetch_top=3 + max_chars=12000 — 3 текста и 32 432 симв. за 23.1с. ⏱ Долгий: один вызов идёт до ~15 мин (внутренний таймаут 900с, столько же ставь таймауту MCP-клиента) — ждать ответа, не поллить.
Inputs: queries (required), mode, expand, as_json, +12 more. Returns: meta, notes, texts, result, +1 more
rssRssARead-onlyIdempotent
КОГДА: следить за обновлениями — новости, блог, changelog, релизы (лента отдаёт даты одним вызовом). ЧТО: посты RSS/Atom: title, link, дата (до limit). НЕ: у URL обычная HTML-страница → fetch_page; следить за лентой целиком → crawl/map_site.
Inputs: url (required), limit. Returns: result
sitemapSitemapARead-onlyIdempotent
КОГДА: нужен полный список страниц сайта — фид для crawl или проверка «что вообще есть на домене». ЧТО: URL из sitemap.xml (+ .xml.gz и вложенные sitemapindex), до max_links. НЕ: у сайта нет sitemap → map_site (ссылки со страницы); тексты → crawl.
Inputs: url (required), max_links. Returns: result
statsСтатистика вызововARead-onlyIdempotent
КОГДА: понять, какие тулы реально работают и что падает — аудит
вызовов и отладка клиента.
ЧТО: по каждому тулу счётчик вызовов, среднее время, ошибки, плюс
последние вызовы (секреты замаскированы). В профилях caps виден
ВСЕГДА (ALWAYS_ON); явные CAMOUFOX_TOOLS_ONLY / CAMOUFOX_TOOL_HIDE
сильнее и могут его убрать.
НЕ: это не метрика «какими тулами пользуются» (её даёт
~/.cache/camoufox-research/tool_usage.json) и
не здоровье сервера (его даёт ping).
Inputs: limit. Returns: result
table_extractИзвлечение таблицARead-onlyIdempotent
КОГДА: на странице есть — прайсы, характеристики, сравнения. ЧТО: CSV-текст таблиц (до max_tables) по CSS-селектору. НЕ: нужных данных в таблице нет → extract; таблиц нет вовсе → fetch_page; JS-грид на div'ах → extract / snapshot.
Inputs: url (required), selector, max_tables. Returns: result
web_searchВеб-поискARead-onlyIdempotent
Когда: БЫСТРЫЙ ОТВЕТ — один запрос, факт, новость, точный URL. Что: номера, заголовки и URL из DuckDuckGo (анти-детект браузер), кэш на сутки; include_snippets — сниппет под URL, pages>1 — пагинация. engines — явный список движков для диагностики (["brave"], ["ddg_html","bing"]), пусто — цепочка из env CAMOUFOX_SEARCH_ENGINES; transport — "auto"/"http"/"browser" (HTTP-фолбэк быстрее, браузер нужен JS/consent-движкам); proxy — разовый прокси на этот вызов ('host:port', 'user:pass@host:port', 'socks5://host:port'); без них поведение прежнее. Не когда: нужно 10+ разных сайтов → research (сейчас); научные статьи → paper_search.
Inputs: query (required), pages, proxy, engines, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools target clearly distinct stages of web research: search, fetch, crawl, extract, export, and monitoring. A few adjacent tools exist (fetch_page vs batch_fetch vs crawl; map_site vs sitemap vs extract_links; extract vs table_extract), but their descriptions explicitly clarify WHEN and NOT WHEN to use each.
All tool names use consistent snake_case English, with no camelCase or mixed conventions. The set is mostly verb_noun or noun_noun, though a few single nouns/verbs (rss, sitemap, stats, ping, crawl, export) are minor deviations from a strict verb_noun pattern.
18 tools is slightly above the ideal 3-15 range, but most earn their place by covering distinct research/scraping workflows. The set does not feel severely bloated, though a few specialized tools could arguably be consolidated.
Core research, fetching, crawling, extraction, document reading, and monitoring are well covered. However, several descriptions reference missing tools such as session_start, session_download, and snapshot, creating dead ends for interactive browsing, downloads, and selector discovery workflows.
Maintenance
Related MCP Connectors
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Web scraping MCP server — scrape, extract structured data, screenshot any site with anti-bot bypass.
MCP server for web extraction and rendering via AceDataCloud WebExtrator
Related MCP Servers
- AlicenseBqualityBmaintenanceAnti-detection browser automation MCP server. 18 tools wrapping CamoFox REST API with stealth fingerprinting that passes bot detection.47581 npm127MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling a local camofox-browser instance, enabling LLM agents to perform web automation tasks such as navigation, interaction, snapshotting, and content extraction.42 npmMIT
- AlicenseBqualityDmaintenanceBrowser automation MCP server using Camoufox anti-detect browser with fingerprint spoofing, geolocation/timezone spoofing, and human-like cursor movement.141Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for multi-engine web search and web page fetching, supporting parallel search, content extraction, and optional LLM-powered search summarization and deep search.6MIT