Skip to main content
Glama
maxmkab
by maxmkab

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: 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_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.jsonlsuccess, 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

F
license - not found
Not graded
quality - not tested
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

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

  • A
    license
    A
    quality
    A
    maintenance
    Enables direct browser control via Chrome DevTools Protocol, supporting navigation, interaction, content extraction, and screenshots through a single MCP tool.
    1
    341
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables 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.
    3
    1
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Browser 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.
    22
    MIT

View all related MCP servers

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.

View all MCP Connectors

Latest Blog Posts

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