de en es ja ko ru zh

browser-agent

Name: browser-agent
Author: maxmkab

by maxmkab

Overview Schema Source Related Servers Discussions Admin

Python

Local

Autonomous Browser Agent — 스크린샷 없이

에이전트는 Playwright를 통해 실제 Chromium을 제어하며, LLM은 이미지가 아닌 구조적 텍스트 스냅샷(ref | role | name | 상태)을 기반으로 결정을 내립니다. Vision 모델이 필요 없으며, 어떤 단계에서도 스크린샷을 촬영하지 않습니다.

하나의 코드베이스에서 세 가지 실행 모드:

모드	활성화 방법	용도
로컬, 브라우저 표시	`HEADLESS=false`	디버깅, 시각적 확인
CDP로 연결한 실제 Chrome	`CDP_URL=http://127.0.0.1:9222`	실시간 세션, 더 나은 핑거프린트
VPS headless 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"
      }
    }
  }
}

또는 한 줄 명령으로:

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을 읽습니다 — 한 줄 = 하나의 작업:

{"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. 프로덕션 전 검증

python main.py snapshot --url <대상 사이트> — 필요한 요소가 스냅샷에 포함되는가?
REQUIRE_APPROVAL=true로 headful 모드에서 로컬 작업 실행.
동일 작업을 로컬 headless로 실행 — 배포 전 렌더링 차이를 포착.
그 후에만 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

agent-browser A
com.scriptmasterlabs
A real Chromium browser agents pay for per action in USDC via x402 — hosted MCP, free local stdio.
Browser Automation Agent Orchestration Payments & Billing
61
https://agent-browser-r7d2.onrender.com/mcp
browser-mcp
io.github.Shreyas-Profile
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser Automation Web Scraping
2
https://browser.regiq.in/api/mcp
BrowserHere
app.1ts.browserhere
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Browser Automation Agent Orchestration
1
https://browserhere.1ts.app/mcp
Irmu — Web Data MCP
io.github.polgoide
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browser Automation Web Scraping Agent Orchestration
1
https://app.irmu.com/mcp

Related MCP Servers

Playwright MCP Server
Browser Automation Testing & QA Tools
muhammadraheel-vd
F
license
Not graded
quality
D
maintenance
Enables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.
Updated 4 months ago (2026-06-22 05:51 UTC)
-
project-tendril
Browser Automation Web Scraping Search
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.
Updated 10 hours ago (2026-11-02 05:22 UTC)
Apache 2.0
Playwright MCP Server
Browser Automation Agent Orchestration Web Scraping
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.
Updated 2 months ago (2026-09-08 15:58 UTC)
Apache 2.0
jev-ultrafast-mcp
Browser Automation Agent Orchestration
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.
Updated a month ago (2026-09-23 12:26 UTC)
10
50 PyPI
20
MIT