Skip to main content
Glama
Sign In
deenesjakoruzh
maxmkab

browser-agent

by maxmkab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Autonomous Browser Agent — スクリーンショットなし

エージェントはPlaywrightを通じて実際のChromiumを操作し、LLMは画像ではなく ページの構造化テキストスナップショット（ref | role | name | 状態）に基づいて判断を下します。 Visionモデルは不要で、どのステップでもスクリーンショットは撮影されません。

同じコードベースから3つの動作モード:

モード

有効化方法

用途

ローカル、可視ブラウザ

HEADLESS=false

デバッグ、視覚的な確認

CDP経由の実際のChrome

CDP_URL=http://127.0.0.1:9222

ライブセッション、より良いフィンガープリント

VPSヘッドレス24/7

HEADLESS=true + Docker/systemd

タスクキューの自律実行

アーキテクチャ

ファイル

役割

snapshot.py

JSインジェクション: DOM + オープンShadow DOM + iframeの走査、可視のインタラクティブ要素の選別、data-agent-ref、LLM用のコンパクトなテキスト

browser.py

Playwrightセッション（headless/headful/CDP、stealth-init、プロキシ、画像ブロック）と14アクションの実行エンジン

llm.py

プランナー: Anthropic / OpenAI互換 / Ollama、厳格なJSONアクションプロトコル

agent.py

LangGraphループ observe → decide → act、履歴圧縮、ループ検出、HITL、制限

main.py

CLI: run、login、snapshot、daemon + Telegram通知と確認

mcp_server.py

MCPサーバー: Claude Code / Cursor / 独自オーケストレーター向けブラウザツール13種

scripts/chrome-cdp.*

デバッグポート付きで自分のChromeを起動（Linux/macOSおよびWindows）

Dockerfile

VPS用 mcr.microsoft.com/playwright/python ベースのイメージ

Related MCP server: project-tendril

1. ローカルマシンへのインストール

git clone https://github.com/maxmkab/autonomous-browser-agent.git
cd autonomous-browser-agent

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
playwright install chromium

cp .env.example .env             # вписать ANTHROPIC_API_KEY

LLMに費用をかけずに確認 — モデルが実際に何を見ているかを確認:

python main.py snapshot --url https://example.com

可視ブラウザでのタスク実行:

HEADLESS=false python main.py run \
  --task "Найди раздел с ценами и извлеки все тарифы через extract" \
  --url https://example.com \
  --json state/report.json

2. 実際のブラウザへの組み込み（CDP）

エージェントは独自のクリーンなChromiumではなく、自分のChromeで動作できます — ライブセッション、 拡張機能、本物のフィンガープリント付きです。拡張機能をインストールする必要はありません — 制御はChrome DevTools Protocol経由で行われます。

# 1) запустить Chrome с открытым портом (отдельный профиль для агента)
chmod +x scripts/chrome-cdp.sh
./scripts/chrome-cdp.sh 9222          # Windows: scripts\\chrome-cdp.bat 9222

# 2) в другом терминале отдать задачу агенту в этом же браузере
CDP_URL=http://127.0.0.1:9222 python main.py run --task "..."

このモードでは、エージェントは storage_state.json に触れません: セッションはChromeプロファイルから取得されます。 初回起動時 — 必要なサービスに手動でログインし、以降はプロファイルがそれを記憶します。

3. MCP経由でのClaude Code / Cursorへの組み込み

mcp_server.py はstdioトランスポートのMCPサーバーを起動します。ツール: browser_open、browser_snapshot、browser_click、browser_type、browser_select、 browser_check、browser_scroll、browser_press、browser_back、browser_tabs、 browser_save_session、browser_run_task、browser_close。

Claude Codeの設定（~/.claude.json またはプロジェクトルートの .mcp.json）:

{
  "mcpServers": {
    "browser-agent": {
      "command": "/absolute/path/autonomous-browser-agent/.venv/bin/python",
      "args": ["/absolute/path/autonomous-browser-agent/mcp_server.py"],
      "env": {
        "HEADLESS": "false",
        "CDP_URL": "http://127.0.0.1:9222",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "REQUIRE_APPROVAL": "true"
      }
    }
  }
}

または1コマンドで:

claude mcp add browser-agent -- /absolute/path/.venv/bin/python /absolute/path/mcp_server.py

これ以降、Claude Codeのモデルは browser_snapshot → browser_click → browser_snapshot のループでブラウザを操作し、テキストスナップショットのみを受け取ります。 ブラウザセッションは呼び出し間で維持されるため、シナリオをステップバイステップで進めることができます。 完全な自律実行には browser_run_task があります — エージェントが自らループを回し、JSONレポートを返します。

4. サーバーへの認証情報の移行

# локально, в видимом окне: залогинился → Enter в консоли
HEADLESS=false python main.py login --url https://site.ru/login

# переносим cookies + localStorage на сервер
scp state/storage_state.json root@YOUR_VPS_IP:/opt/browser-agent/state/

5. VPSへのデプロイ（Ubuntu 24.04 + Docker）

mkdir -p /opt/browser-agent/state && cd /opt/browser-agent
git clone https://github.com/maxmkab/autonomous-browser-agent.git .
cp .env.example .env && nano .env

docker build -t browser-agent .
docker run -d --name browser-agent --restart unless-stopped \
  --shm-size=1g \
  --env-file .env \
  -v /opt/browser-agent/state:/app/state \
  browser-agent

--shm-size=1g は必須です: デフォルトの64MBの/dev/shmを持つコンテナ内のChromiumは、 重いページでクラッシュします。

サーバーでの単発タスク:

docker exec -it browser-agent python main.py run --task "..." --url https://...

Dockerなし（systemd）

apt update && apt install -y python3-venv
cd /opt/browser-agent && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium

/etc/systemd/system/browser-agent.service:

[Unit]
Description=Autonomous browser agent
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/browser-agent
EnvironmentFile=/opt/browser-agent/.env
ExecStart=/opt/browser-agent/.venv/bin/python main.py daemon --interval 300
Restart=always
RestartSec=10
StandardOutput=append:/var/log/browser-agent.log
StandardError=append:/var/log/browser-agent.log

[Install]
WantedBy=multi-user.target
systemctl daemon-reload && systemctl enable --now browser-agent
journalctl -u browser-agent -f

6. タスクの設定とn8n

デーモンは state/tasks.jsonl を読み取ります — 1行 = 1タスク:

{"id":"price-check-1","task":"Открой карточку товара, извлеки цену и наличие через extract","url":"https://site.ru/item/123"}
{"id":"lead-form","task":"Заполни форму заявки: имя Иван, телефон +79990000000. Отправку подтвердит человек."}

結果は state/results.jsonl に success、result、extracted、 steps、tokens_in/out フィールドと完全なトレース history とともに書き込まれます。n8nはこのファイルにタスクを書き込み （Execute Command / SSHノード）、結果を読み取ることができます。

7. トークン節約

  • スクリーンショットなし: テキストのみ、visionモデルなし。

  • DOMフィルタリング: コンテキストには可視のインタラクティブ要素で名前が空でないもののみ、フレームあたり最大250個。

  • ネットワークレベルでの画像/フォント/メディアのブロック（BLOCK_MEDIA=true）。

  • 履歴圧縮（HISTORY_WINDOW）: 完全なスナップショットは直近のステップのみ、古いものは action → result に圧縮。

  • ループ検出: スナップショットのフィンガープリントが変わらない場合、モデルに戦略変更の指示が出されます。

8. セキュリティ

RISKY_PATTERNS（支払い、購入、注文、削除、送信、 checkout、pay、delete）に該当するアクションは確認が必要です: ローカルではコンソールで、サーバーではTelegramで「はい」と回答 （APPROVAL_MODE=telegram）。ALLOW_EVAL=false がデフォルトで任意のJS実行を禁止します。 すべてのアクションエラーはobservationとしてモデルに返され、プロセスをクラッシュさせません。 シークレットはgitから除外された .env にのみ保存されます。

9. 本番環境前の確認

  1. python main.py snapshot --url <対象サイト> — 必要な要素がスナップショットに含まれていますか?

  2. REQUIRE_APPROVAL=true でheadfulでローカルにタスクを実行。

  3. 同じタスクをローカルでheadless実行 — デプロイ前にレンダリングの差異を検出。

  4. その後でのみVPSにデプロイしてデーモンを起動。

ライセンス

MIT

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • project-tendril

    gadgethd
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to operate an isolated local Chromium browser through MCP, with semantic snapshots, ref-based actions, search, research, crawling, and CDP access.
    Apache 2.0

  • Playwright MCP Server

    tomscoppock
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents and clients to control a real Chromium browser through MCP tool calls, including navigation, clicking, typing, JavaScript evaluation, screenshots, and DOM snapshots. Supports multiple isolated sessions over authenticated HTTP with no disk writes.
    Apache 2.0

  • jev-ultrafast-mcp

    jiawei686
    A
    license
    A
    quality
    A
    maintenance
    Enables AI agents to drive a Chromium browser over MCP, reading pages as a numbered list of controls and performing actions like clicking, filling forms, and asserting page state without screenshots or API keys.
    10
    50 PyPI
    20
    MIT