camoufox-research
Camoufox Research
AIエージェント向けブラウザリサーチツールキット。MCP経由で公開。
ウェブを検索。JS多用ページを読む。ウェブサイトと対話。データ抽出。変更監視。 AIエージェントに本物のブラウザを。
AI Agent
│ (tools, resources, prompts)
▼
MCP
│
▼
Camoufox Research ← this server (48 tools)
│
▼
Camoufox ← anti-detect Firefox
│
▼
WebほとんどのMCPサーバーはウェブを読むことができます。これはその中に住むことができます:ページを開き、 クリック、入力、フォーム送信、ファイルアップロード、ネットワークトラフィック監視、ラベル付き スクリーンショット、サイト全体のクロール、テーブル抽出、変更監視 — そしてそのすべてを MCP(stdio、HTTP、またはSSE)経由でエージェントに渡します。
Camoufox Researchが選ばれる理由
ほとんどのMCPブラウザツールはエージェントに孤立したアクションを与えます。ここでの目標は 異なります:ウェブリサーチのための完全なツールキット — エージェントが最初から最後まで 使える1つのサーバー。
🔎 検索 — 情報源を見つける(非検出ブラウザ経由のDuckDuckGo、10以上の情報源を使った深い
research)🌐 ブラウズ — JS/SPAページを読み、タブ、クリック、フォーム、アップロードを備えたライブセッション
👁️ ページを理解 — ラベル付きスクリーンショット(Set-of-Mark)、ref付きスナップショットツリー
📊 抽出とエクスポート — CSS/XPathによるフィールド、テーブル→CSV、PDF/DOCX/XLSX、JSON/Markdownファイル
Related MCP server: camofox-browser-mcp
⚡ 30秒デモ
"このウェブサイトのすべての価格ページを見つけて、価格を抽出してCSVに保存して。"
Agent
├─ map_site discover every /pricing page
├─ crawl read them (cached)
├─ extract {"plan": "css:.plan", "price": "css:.price"}
└─ export format=csv → prices.csvブラウザ自動化コードは不要。エージェントへの一言だけ。
できること(実際のシナリオ)
🔎 リサーチ — "このプロジェクトについての情報を見つけて、10の情報源を確認して要約して。"
research→fetch_page→export
🕷 クロール — "サイト全体を歩いて、すべてのドキュメントページを見つけて。"
sitemap→crawl/map_site
📊 抽出 — "テーブルから価格を集めてCSVとして保存して。"
extract/table_extract→export
👁 ビジョン — "ページを見て、Downloadボタンを見つけて押して。"
screenshot(som=True)→snapshot→session_click(ref="4")
📡 監視 — "このページをチェックして、変更があったか教えて。"
fetch_page→page_diff(デルタ読み取りでトークン節約)
1つの完全なシナリオ(キラーデモ)
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)そしてエージェントにこう頼みます:
"Camoufoxに関する最新記事を見つけて、比較して、結果を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.mdそれが要点です:あなたのエージェントが本物のブラウザを操作し、あなたは目標を説明するだけ。
ツールが必要?ここから始めよう
必要なもの | ツール |
情報を見つける |
|
ページを読む(JS/SPAでも) |
|
複数ページを一度に読む |
|
サイト全体を歩く |
|
特定のフィールドを取得(CSSまたはXPath) |
|
テーブル→CSV |
|
クリック / 入力 / キー押下 |
|
インターフェースを理解 |
|
フォームを1回で埋める |
|
ファイルをアップロード |
|
ファイルをダウンロード |
|
ネットワーク / JSコンソール監視 |
|
変更を追跡 |
|
PDF / DOCX / XLSXを読む |
|
RSS / sitemapフィード |
|
壊れたリンクをチェック |
|
結果をディスクに保存 |
|
ログインを保持 |
|
プロキシを動的に変更 |
|
サーバーが何をしたか見る |
|
ビジョン — 番号付きページ

Screenshot snapshot agent
│ │ │
▼ ▼ ▼
┌──────────┐ - ref: 3 session_click(ref="3")
│ [1][2][3]│ - tag: a ───► browser clicks exact element
│ [4] [5] │ - text: "Download"
└──────────┘snapshot はインタラクティブ要素のコンパクトなYAMLツリーを返します(100 KB+のHTMLの代わりに約2〜5 KB)、
各要素に ref が付いています。ref でクリック、壊れやすいセレクタは不要。
クイックスタート
# 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 fetchMCPクライアント(OpenCode / Claude Desktop / Cursor)に接続 — MCPに接続 を参照。
エージェントにウェブサイトをリサーチしてもらいます:
"Camoufoxに関する最新記事を見つけて、比較して、結果をMarkdownに保存して。"
インストール
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;
Pythonはpython.org(MS Storeではない)とVC++再頒布可能パッケージが必要です。
MCPに接続
opencode (~/.config/opencode/opencode.json):
{
"mcp": {
"camoufox": {
"type": "local",
"command": ["/path/to/venv/bin/camoufox-research"],
"enabled": true
}
}
}Claude Desktop、Cursorなど — すぐ使える例は mcp/config/ にあります。
インストール不要:python mcp/server.py はソースから動作します。
確認: opencode mcp list → camoufox: connected。
ツール(48)
グループ | ツール |
リサーチ |
|
読み取り |
|
構造 |
|
データ |
|
ビジョン |
|
ブラウザ |
|
ライブセッション |
|
ネットワーク |
|
ファイル |
|
可観測性 |
|
ネットワーク設定 |
|
サービス |
|
MCPリソースとプロンプト
リソース(「ファイルとして」読み取れるデータ):
camoufox://stats,camoufox://cache,camoufox://session,camoufox://infoプロンプト(既製レシピ):
research_plan,extract_schema,monitor_page
トランスポート
stdio (デフォルト), http, sse:
camoufox-research --transport http --port 8833 # or env CAMOUFOX_PORT動作
ブラウザは別のワーカープロセス(同期、ヘッドレス)で動作 — MCP stdio サーバーはブロックしません。
JS/SPAページは準備なしで読み取られます:コンテンツポーリング+スクロール+ 安定性検出; 空→再試行。
キャッシュ: sqlite
~/.cache/camoufox-research/cache.db, TTL 24時間, バックオフ付き再試行;delta=Trueは変更のないページの再読み取りをスキップ。設定は環境変数のみ(
configs/example.envを参照):CAMOUFOX_VENV,CAMOUFOX_CACHE_DIR, タイムアウト, プロキシ。
開発
CONTRIBUTING.md を参照:レイアウト、新しいツールの追加、スモークテストの儀式。
CI
プッシュごとにGitHub Actions:Python 3.10/3.11/3.12でのインストール、インポートチェック、
MCP stdioスモーク(initialize → tools/list → ping)。完全なブラウザテストは
ローカルで実行(scripts/update_camoufox.py + 手動スモーク)。
経験ジャーナル
EXPERIENCE.md — 検証済みの教訓と地雷(「踏んではいけないもの」): asyncio/serveの落とし穴、403-vs-urllib、非スレッドセーフなPlaywright、 ElementTree XPathの制限など。
依存ライセンス
camoufox — そのリポジトリを参照
mcp — MIT
trafilatura — GPL-3.0 (オプション: テキスト抽出)
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