browser-guard-mcp

English: README.en.md · 설계 문서: docs/설계서.md

AI 에이전트를 위한 브라우저 자동화 — 다층 안전 가드 내장 MCP 서버.

LLM 에이전트에 브라우저를 그대로 열어주는 건 위험합니다. 이 서버는 Playwright를 가드 뒤에서 열어줍니다 — 허용된 도메인만 이동하고, 기본은 읽기 전용이며, 모든 행동(차단된 시도 포함)이 감사 로그에 남습니다.

이런 상황에서 씁니다

상황 — 운영팀이 매일 아침 경쟁사·제휴사 페이지 몇 곳을 눈으로 확인한다(가격, 공지, 재고). 에이전트에게 시키고 싶지만, 브라우저를 통째로 주면 엉뚱한 사이트로 가거나 뭔가 눌러버릴까 불안하다.

도입 후 — 확인 대상 도메인만 허용목록에 넣고 읽기 전용으로 물린다. "이 세 페이지 열어서 가격 바뀐 것 있는지 알려줘"가 안전한 일상 업무가 된다 — 클릭·제출은 코드 수준에서 불가능하고, 에이전트가 어디서 무엇을 봤는지(차단된 시도까지) 감사 로그에 남는다.

Related MCP server: MCP Playwright Server

가드 계층

도구

browser_navigate · browser_get_text · browser_click · browser_fill · browser_screenshot · browser_guard_status · browser_audit_log

데모

동봉된 가짜 쇼핑몰(demo_site/)로 외부 인터넷 없이 시연할 수 있습니다.

• "데모 상점 열어서 3만 원 이하 상품 알려줘" → 정상 조회

• "무선 마우스 주문해줘" → 거절 — 읽기 전용 모드라 클릭 불가, 에이전트가 이유를 설명

• "구글에서 검색해봐" → 거절 — 허용목록 밖, 허용된 도메인 목록 안내

프롬프트가 아니라 코드가 강제하는 안전입니다.

MCP 클라이언트 없이 가드 동작만 눈으로 보고 싶다면 examples/ 스크립트 참조:

• demo_guard.py — 브라우저 없이 가드 로직만 (도메인 차단·경로 탈출·읽기 전용·텍스트 상한)

• demo_browser.py — 실제 headless Chromium으로 데모 사이트 열기

• demo_browser_headed.py — 브라우저 창을 눈으로 보고 싶을 때 (headless=False)

설치

pip install -e .
playwright install chromium

export BROWSERGUARD_ALLOWED_DOMAINS="books.toscrape.com,quotes.toscrape.com"
export BROWSERGUARD_READ_ONLY="true"   # 기본값 — 조회·스크린샷만

위 명령으로 설치하면 browser-guard-mcp 커맨드가 생깁니다 (pyproject.toml의 [project.scripts]). 이 자체로는 그냥 실행 가능한 서버일 뿐이고, 실제로 에이전트가 쓰게 하려면 MCP 클라이언트에 등록해야 합니다.

MCP 클라이언트에 연결

Claude Desktop — examples/claude_desktop_config.json 내용을 claude_desktop_config.json에 병합 후 재시작:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "browser-guard": {
      "command": "browser-guard-mcp",
      "env": {
        "BROWSERGUARD_ALLOWED_DOMAINS": "books.toscrape.com,quotes.toscrape.com",
        "BROWSERGUARD_READ_ONLY": "true"
      }
    }
  }
}

Claude Code(CLI):

claude mcp add browser-guard -- browser-guard-mcp

가상환경에만 설치했다면 클라이언트가 PATH에서 browser-guard-mcp를 못 찾을 수 있습니다 — 이때는 command에 절대경로(예: /path/to/.venv/bin/browser-guard-mcp)를 지정하세요.

테스트

pip install -e ".[dev]"
pytest   # 19건, 브라우저·네트워크 불필요 — 위장 도메인, 경로 탈출, 읽기 전용, 차단 시 브라우저 미호출

함께 보기

• sql-guard-mcp — 같은 원칙의 SQL 버전: 능력을 주되 부주의를 불가능하게

• judge-mcp · log-triage-agent · llm-sse-gateway

라이선스

MIT