Skip to main content
Glama
camoufox-research

camoufox-research

by aidvizhhub

Camoufox Research

AIエージェント向けブラウザリサーチツールキット。MCP経由で公開。

ウェブを検索。JS多用ページを読む。ウェブサイトと対話。データ抽出。変更監視。 AIエージェントに本物のブラウザを。

Python CI MCP Camoufox Version

    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

それが要点です:あなたのエージェントが本物のブラウザを操作し、あなたは目標を説明するだけ。

ツールが必要?ここから始めよう

必要なもの

ツール

情報を見つける

web_search

ページを読む(JS/SPAでも)

fetch_page

複数ページを一度に読む

batch_fetch

サイト全体を歩く

crawl / sitemap

特定のフィールドを取得(CSSまたはXPath)

extract

テーブル→CSV

table_extract

クリック / 入力 / キー押下

browser_click, session_click, session_type, session_key_press

インターフェースを理解

screenshot(som=True), snapshot (refs)

フォームを1回で埋める

session_form_fill

ファイルをアップロード

session_upload

ファイルをダウンロード

session_download

ネットワーク / JSコンソール監視

session_network, session_console

変更を追跡

page_diff, fetch_page(delta=True)

PDF / DOCX / XLSXを読む

read_document

RSS / sitemapフィード

rss

壊れたリンクをチェック

check_links

結果をディスクに保存

export (json / csv / md)

ログインを保持

profile_save / profile_load

プロキシを動的に変更

set_proxy

サーバーが何をしたか見る

stats (監査、シークレットはマスク)

ビジョン — 番号付きページ

Vision demo: page → Set-of-Mark numbered overlay

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 fetch
  1. MCPクライアント(OpenCode / Claude Desktop / Cursor)に接続 — MCPに接続 を参照。

  2. エージェントにウェブサイトをリサーチしてもらいます:

"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-research

Windows: 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)

グループ

ツール

リサーチ

research (深い検索+読み取り), web_search

読み取り

fetch_page (+ delta), batch_fetch, extract_links, read_document (PDF/DOCX/XLSX)

構造

extract (CSS + XPath), crawl (BFS), map_site, sitemap (+.gz, ネスト), table_extract

データ

export (json/csv/md), rss, check_links

ビジョン

screenshot (+ som=True — Set-of-Mark), snapshot (refs)

ブラウザ

browser_navigate, browser_click (+ref), browser_type

ライブセッション

session_start/navigate/click/type/scroll/links/text/back/status/end, session_tabs, session_wait_for, session_eval, session_key_press, session_select_option, session_resize, session_form_fill, session_upload

ネットワーク

session_network, session_console, session_block/session_unblock

ファイル

session_download, page_diff

可観測性

stats (監査、マスク), cache_info

ネットワーク設定

set_proxy, profile_save/profile_load

サービス

ping

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 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