browser-agent
Autonomous Browser Agent — 스크린샷 없이
에이전트는 Playwright를 통해 실제 Chromium을 제어하며, LLM은 이미지가 아닌
구조적 텍스트 스냅샷(ref | role | name | 상태)을 기반으로 결정을 내립니다.
Vision 모델이 필요 없으며, 어떤 단계에서도 스크린샷을 촬영하지 않습니다.
하나의 코드베이스에서 세 가지 실행 모드:
모드 | 활성화 방법 | 용도 |
로컬, 브라우저 표시 |
| 디버깅, 시각적 확인 |
CDP로 연결한 실제 Chrome |
| 실시간 세션, 더 나은 핑거프린트 |
VPS headless 24/7 |
| 작업 큐 기반 자율 실행 |
아키텍처
파일 | 용도 |
| JS 인젝트: DOM + 오픈 Shadow DOM + iframe 순회, 보이는 상호작용 요소 선별, |
| Playwright 세션(headless/headful/CDP, stealth-init, 프록시, 이미지 차단) 및 14개 액션 실행기 |
| 플래너: Anthropic / OpenAI 호환 / Ollama, 엄격한 JSON 액션 프로토콜 |
| LangGraph 루프 |
| CLI: |
| MCP 서버: Claude Code / Cursor / 자체 오케스트레이터용 브라우저 도구 13개 |
| 디버그 포트로 내 Chrome 실행 (Linux/macOS 및 Windows) |
| VPS용 |
Related MCP server: Playwright MCP Server
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_KEYLLM 비용 없이 확인 — 모델이 정확히 무엇을 보는지 확인:
python main.py snapshot --url https://example.com브라우저를 표시한 상태로 작업 실행:
HEADLESS=false python main.py run \
--task "Найди раздел с ценами и извлеки все тарифы через extract" \
--url https://example.com \
--json state/report.json2. 실제 브라우저에 통합 (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.targetsystemctl daemon-reload && systemctl enable --now browser-agent
journalctl -u browser-agent -f6. 작업 등록 및 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 installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables direct browser control via Chrome DevTools Protocol, supporting navigation, interaction, content extraction, and screenshots through a single MCP tool.1341MIT
- FlicenseNot gradedqualityCmaintenanceEnables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.
- AlicenseNot gradedqualityBmaintenanceEnables Codex to control a visible Chromium browser via MCP tools for navigation, page inspection, and interaction, while keeping sensitive steps like login and captcha under the user's control.31MIT
- AlicenseAqualityBmaintenanceBrowser automation MCP server that uses a real browser to give agents eyes and hands—open pages, click, fill, screenshot, and run scripts via accessibility-tree snapshots.22MIT
Related MCP Connectors
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxmkab/autonomous-browser-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server