Skip to main content
Glama
camoufox-research

camoufox-research

by aidvizhhub

Camoufox Research

An MCP server that gives your AI agent a real browser — search the web, read JS/SPA pages, click, fill forms, crawl sites, extract tables, save files, watch for changes. Runs on the anti-detect Camoufox (Firefox), so pages see a normal browser instead of a headless bot.

По-русски: MCP-сервер для веб-ресёрча. Даёт агенту живой браузер — поиск, чтение тяжёлых страниц, клики, формы, сбор данных. Ставится одной командой.

30-second demo

Python CI MCP Camoufox Version Tools License Showcase

46 tools total, 18 in the default profile — a profile is just the set of tool groups you switch on (--caps); fewer tools make the agent choose better.

AI agent ──MCP──▶ Camoufox Research ──▶ Camoufox (anti-detect Firefox) ──▶ web

Why

Most MCP browser servers hand an agent isolated actions. This one is a complete research toolkit in a single server — the agent searches, reads, interacts and exports without you writing browser code.

  • 🔎 Search — live web search that keeps working when a source is blocked, plus deep research that gathers 10+ sources across many distinct sites in one call

  • 🌐 Browse — JS/SPA text, live sessions with tabs, clicks, forms, uploads

  • 👁️ See pages — Set-of-Mark screenshots and a compact snapshot tree with refs

  • 📊 Extract — CSS/XPath fields, tables → CSV, PDF/DOCX/XLSX, export JSON/MD

Related MCP server: camofox-browser-mcp

30-second demo

"Find all pricing pages on this site, extract the prices and save them to CSV."

Agent
 ├─ map_site     discover every /pricing page
 ├─ crawl        read them (cached)
 ├─ extract      {"plan": "css:.plan", "price": "css:.price"}
 └─ export       format=csv  →  prices.csv

No browser-automation code — just a sentence to your agent.

Install (one command)

Requirements: Python 3.10–3.13 and git (Windows: also PowerShell 7). The installer creates a venv, installs the package from the clone, downloads the browser once, registers the MCP server and checks the handshake. There is no PyPI package — the code comes from this repo or Docker.

OS

One command (from the clone root)

Linux (Fedora/Ubuntu/Debian/Arch/…)

bash scripts/install.sh

macOS

bash scripts/install.sh (same script; no system packages needed)

Windows (native, PowerShell 7)

pwsh -NoProfile -File scripts\install.ps1

Docker (any OS with Docker)

bash scripts/install/run_in_docker.sh --build --run

No clone, one command (uv) or the prebuilt image

uv installs the package straight from this repo — no clone, no PyPI:

uv tool install git+https://github.com/aidvizhhub/camoufox-research
camoufox-research                 # stdio MCP server; browser downloads on first run

One-shot without installing (uvx) — handy for an MCP client:

uvx --from git+https://github.com/aidvizhhub/camoufox-research camoufox-research

The image is prebuilt in GHCR (browser already inside, nothing to fetch):

docker run -i --rm -v camoufox-data:/data ghcr.io/aidvizhhub/camoufox-research:latest

server.json carries the MCP Registry metadata and points at that image. There is no PyPI package by design — git, uv, or Docker.

Preview first — it changes nothing:

bash scripts/install.sh --dry-run                    # plan for THIS machine
pwsh -NoProfile -File scripts\install.ps1 -WhatIf    # Windows plan

No clone yet? The same installer pulls the repo to ~/camoufox-research:

curl -fsSL https://raw.githubusercontent.com/aidvizhhub/camoufox-research/main/scripts/install.sh | bash

Windows: irm …/install.ps1 | iex. Full matrix, flags and troubleshooting — docs/install-crossplatform.md; native Windows details — docs/install-windows.md.

Check after install:

~/.venvs/camoufox-research/bin/python scripts/checks/mcp_probe.py   # caps → handshake → tools count
opencode mcp list               # opencode: camoufox connected
claude mcp list                 # Claude Code; Claude Desktop / Cursor — status in their UI

Update, or remove (cache and browser stay):

bash scripts/install/update_mcp.sh           # pull → pip → reconnect
bash scripts/install.sh --reinstall  # reinstall the package from the clone
bash scripts/install.sh --uninstall  # venv + MCP entry; cache/browser kept

By hand, if you already have a clone and want full control:

python3 -m venv ~/.venvs/camoufox-research
~/.venvs/camoufox-research/bin/pip install .
~/.venvs/camoufox-research/bin/python -m camoufox fetch   # browser, once

pip install . installs the code on disk — not from PyPI. Optional extras: pip install '.[geoip]' adds IP-based geolocation, locale and timezone for proxied runs (only active with a proxy and CAMOUFOX_GEOIP=1). The common env vars (CAMOUFOX_*: cache dir, timeouts, caps, report dir) are documented in configs/example.env; the advanced switches (stealth, SSRF, budgets, LLM planner, transports) live in the code — list them all with grep -rhoE 'CAMOUFOX_[A-Z0-9_]+' camoufox_research/ | sort -u.

Connect to MCP

The installer writes the client config for you. To do it by hand, the canon is opencode v2: the config is ~/.config/opencode/opencode.jsonc and servers live under mcp.servers.<name> — not mcp.<name>, and disabled — not enabled (the old v1 shape is silently ignored by v2).

OpenCode (~/.config/opencode/opencode.jsonc): copy-ready section — mcp/config/opencode.jsonc.example.

Claude Desktop and Cursor use their own shape (mcpServers + command string + env); copy-ready files are in mcp/config/ (claude_desktop_config.json.example, cursor_mcp.json.example). Trying it from sources still means installing once (the MCP SDK lives in the venv); then run the console script from that venv: ~/.venvs/camoufox-research/bin/camoufox-research. Don't launch mcp/server.py from the repo root — the local mcp/ folder shadows the SDK and the import fails.

Installed with uv (no clone)? Use as command (same opencode v2 shape): ["uvx", "--from", "git+https://github.com/aidvizhhub/camoufox-research", "camoufox-research"].

Check — CLI opencode mcp list → ✓ camoufox connected; inside a session the /mcps command shows the same status. A one-page walkthrough (path, paste, troubleshooting) is in mcp/config/opencode-connect.md.

Tools (46)

Tools are grouped, and the groups double as --caps profiles (see below).

Group

Tools

Count

research

web_search, research, paper_search

3

browser

fetch_page, batch_fetch, extract_links, extract, table_extract, crawl, map_site, sitemap, rss, read_document, check_links, export, page_diff

13

session

session_* (tabs, clicks, forms, keys, JS, network, files), set_proxy, profile_save/load

26

vision

snapshot (refs), screenshot (som=True)

2

always on

ping, stats (audit, secrets masked)

2

A few things worth knowing:

  • Search runs a chain of independent engines: one that is blocked or returns nothing cools down and the query moves on; results are cached per engine+query, so a blocked source never takes web_search down. For engines that need a proxy there is a pool (CAMOUFOX_SEARCH_PROXY / CAMOUFOX_SEARCH_PROXIES).

  • fetch_page reuses a 24 h cache — a repeat costs no network. delta=True returns a marker when nothing changed (saves answer tokens) but still does a fresh fetch — use it for "what changed", not for cheap repeats.

  • snapshot returns a ~2–5 KB YAML tree of interactive elements with a ref on each — click by ref, no fragile selectors.

  • research runs a deep hunt in one call: query expansion, quality ranking (docs/GitHub/arXiv first), domain dedup, and honest partial when the goal isn't reached. For a single fact, use web_search.

  • export writes JSON / CSV / Markdown to disk.

Tool profiles (fewer tools, better choice)

46 tools in one prompt degrade an agent's tool choice (industry rule of thumb: past ~40 it drops). Pick the groups you need — the same idea as Playwright MCP's --caps:

camoufox-research --caps research,browser     # or env CAMOUFOX_CAPS

Profile

Tools

What's inside

research,browser (default)

18

search + reading/extraction

research,browser,session

44

+ live tab, forms, network, files

research,browser,vision

20

+ snapshot (refs) and screenshot (PNG)

all

46

the full registry

ping/stats are always available. CAMOUFOX_TOOLS_ONLY / CAMOUFOX_TOOL_HIDE still apply on top. Invalid group → warning, valid groups still load.

MCP resources & prompts

  • Resources: camoufox://stats, camoufox://cache, camoufox://session, camoufox://info, camoufox://health, camoufox://search

  • Prompts: research_plan, extract_schema, monitor_page

Transports

stdio (default), streamable-http (stateless; the remote option), sse (legacy, kept for the 2026-07-28 spec's 12-month window):

camoufox-research --transport http --port 8833
CAMOUFOX_PORT=8833 camoufox-research --transport http

Troubleshooting

Unknown tool usually means the client is still talking to an old server — a restart after a code change fixes it. A one-command, read-only diagnosis:

~/.venvs/camoufox-research/bin/python scripts/checks/mcp_probe.py            # human-readable
~/.venvs/camoufox-research/bin/python scripts/checks/mcp_probe.py --json     # machine-readable

It shows python / repo → caps → protocol handshake → how many tools tools/list returns → package version → search-watchdog pulse. A small tools=N or a failed handshake means stale code in the venv → reinstall from the clone (bash scripts/install.sh --reinstall) and reconnect (API disconnect/connect, not kill).

Honest numbers

There is no single head-to-head here. The three numbers below come from one third-party benchmark run; ours come from separate runs on a smaller sample. They sit next to each other for context — not as the same measurement.

Reference (not our run): fastCRW diagnose_3way.py scoring (phrases > 20 chars, recall >= 0.3 = found) on the public dataset firecrawl/scrape-content-dataset-v1 — measured 2026-05-08 over the full 819 URLs:

Tool

Truth-recall

fastCRW

63.7% (522/819)

Crawl4AI

60.0% (491/819)

Firecrawl

56.0% (459/819)

Our own number is deliberately kept out of that table. Our script runs a 30-URL prefix of the same dataset, so the comparison is indirect — different sample size and a different date. At n=30 the 95% confidence interval is roughly ±18 p.p., wider than the gap between all the tools above. Two runs on 2026-09-29 gave 36.7% (11/30) and 40.0% (12/30), and a re-run within 24h measures the page cache rather than the web. Read it as a smoke number for the extractor, not as a leaderboard position. Reproduce with python scripts/dev/bench_truth_recall.py --sample N.

Documentation

Doc

What's there

docs/agent-usage.md

guide for the agent: profiles, call order, limits, pitfalls

docs/RESEARCH-PLAYBOOK.md

recipes for fast / full / deep research, measured chars and seconds

docs/VERIFICATION.md

what was verified live and by what, plus an honest "what was NOT verified"

docs/install-crossplatform.md

install matrix: Linux / macOS / Windows / Docker

docs/install-windows.md

native Windows (PowerShell 7) install notes

docs/ARCHITECTURE.md

layers, modules, state, extension points, debts

docs/landmines.md

verified landmines ("what not to step on") — index in EXPERIENCE.md

SECURITY.md

how to report a vulnerability (private advisory), scope, supported versions

Development

See CONTRIBUTING.md: layout, how to add a tool, the live-smoke ritual and the unit tests (pip install -e ".[dev]" → pytest -q). CI runs pytest, py_compile + import + an MCP stdio smoke on Python 3.10–3.13, plus the lint/filesize/version gates; full browser flows are checked locally.

License

MIT — see LICENSE.

Dependencies: camoufox (see its repo), mcp (MIT), trafilatura (GPL-3.0; обязательна — read_document/table_extract и article_only извлекают ею, без неё чтение деградирует до текста всего body).

Available Tools

18 tools
batch_fetchПакетное чтениеA
Read-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

crawlОбход сайтаA
Read-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Экспорт результатаA
Destructive

КОГДА: результат нужен файлом на диске — CSV для таблиц, JSON для автоматизации, MD для отчёта. ЧТО: файл (json/csv/md) по своему path или авто в ~/.cache/camoufox-research/exports/. НЕ: результат идёт в разговор и синтез → отдай текст как есть.

Inputs: data (required), path, format. Returns: result

extractИзвлечение полейA
Read-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

fetch_pageЧтение страницыA
Read-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Карта сайтаA
Read-onlyIdempotent

КОГДА: понять структуру сайта — какие разделы и страницы есть, без чтения содержимого. ЧТО: ссылки того же домена со стартовой страницы (до max_links), pattern — фильтр по URL. НЕ: нужны тексты → crawl; есть sitemap.xml → sitemap (полнее и дешевле); одна страница → fetch_page.

Inputs: url (required), pattern, max_links. Returns: result

page_diffДифф страницыA
Read-onlyIdempotent

КОГДА: страницу уже читали, и нужно узнать, что ИЗМЕНИЛОСЬ — цены, доки, новости (мониторинг, второй и далее заходы). ЧТО: дифф свежего чтения с прошлым из кэша, «что поменялось». НЕ: страница читается впервые — сравнивать не с чем, сначала fetch_page; нужна полная текстовая версия → fetch_page.

Inputs: url (required), max_chars. Returns: result

pingПроверка связиA
Read-onlyIdempotent

Проверка связи: возвращает pong.

Это ПРИКЛАДНОЙ health-тул, а не протокольный ping (его в спеке 2026-07-28 убрали). Имя оставлено публичным контрактом — менять нельзя.

Inputs: no named parameters. Returns: result

read_documentЧтение документаA
Read-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Глубокий ресёрчA
Read-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

rssRssA
Read-onlyIdempotent

КОГДА: следить за обновлениями — новости, блог, changelog, релизы (лента отдаёт даты одним вызовом). ЧТО: посты RSS/Atom: title, link, дата (до limit). НЕ: у URL обычная HTML-страница → fetch_page; следить за лентой целиком → crawl/map_site.

Inputs: url (required), limit. Returns: result

sitemapSitemapA
Read-onlyIdempotent

КОГДА: нужен полный список страниц сайта — фид для crawl или проверка «что вообще есть на домене». ЧТО: URL из sitemap.xml (+ .xml.gz и вложенные sitemapindex), до max_links. НЕ: у сайта нет sitemap → map_site (ссылки со страницы); тексты → crawl.

Inputs: url (required), max_links. Returns: result

statsСтатистика вызововA
Read-onlyIdempotent

КОГДА: понять, какие тулы реально работают и что падает — аудит вызовов и отладка клиента. ЧТО: по каждому тулу счётчик вызовов, среднее время, ошибки, плюс последние вызовы (секреты замаскированы). В профилях caps виден ВСЕГДА (ALWAYS_ON); явные CAMOUFOX_TOOLS_ONLY / CAMOUFOX_TOOL_HIDE сильнее и могут его убрать. НЕ: это не метрика «какими тулами пользуются» (её даёт ~/.cache/camoufox-research/tool_usage.json) и не здоровье сервера (его даёт ping).

Inputs: limit. Returns: result

table_extractИзвлечение таблицA
Read-onlyIdempotent

КОГДА: на странице есть — прайсы, характеристики, сравнения. ЧТО: CSV-текст таблиц (до max_tables) по CSS-селектору. НЕ: нужных данных в таблице нет → extract; таблиц нет вовсе → fetch_page; JS-грид на div'ах → extract / snapshot.

Inputs: url (required), selector, max_tables. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 18 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Browser automation MCP server using Camoufox anti-detect browser with fingerprint spoofing, geolocation/timezone spoofing, and human-like cursor movement.
      14
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for multi-engine web search and web page fetching, supporting parallel search, content extraction, and optional LLM-powered search summarization and deep search.
      6
      MIT