webshot-mcp

당신의 에이전트에게 눈을 부여하세요 — 브라우저나 네트워크를 노출하지 않고서도. 두 가지 도구(screenshot, page_text)를 제공하는 MCP 서버로, 이미 실행 중인 Chrome(CDP를 통해)에 연결하여 전체 페이지 또는 단일 요소를 캡처합니다. 브라우저를 실행하거나 다운로드하지 않으며, SSRF를 인식하는 URL 정책에 따라 사설 네트워크 대상은 차단됩니다.

존재 이유

시각적 확인 → 수정 루프를 코딩 에이전트와 함께 실행하며 얻은 두 가지 교훈:

1. 스크린샷마다 브라우저를 실행하는 것은 느리고 불안정한 방법입니다. 지속적인 헤드리스 Chromium(Docker 사이드카, CI 서비스, --remote-debugging-port가 있는 데스크톱 Chrome)은 워밍업되어 있고 공유되며 안정적입니다. 부족한 것은 훈련된 클라이언트입니다: CDP로 연결하고, 샷마다 새로운 컨텍스트를 열고, 연 것만 닫고, 공유 브라우저는 절대 종료하지 않는 것. 그 훈련이 이 레포지토리입니다.

2. 네트워크 내부의 스크린샷 도구는 카메라가 달린 SSRF 프록시입니다. http://169.254.169.254/… 또는 http://redis.internal:6379/를 "스크린샷" 하도록 설득될 수 있는 에이전트는 기꺼이 클라우드 메타데이터 엔드포인트를 촬영할 것입니다. 따라서 URL 정책은 루프백, RFC-1918, 링크-로컬, CGNAT 및 v6-로컬 대상을 차단합니다. 여기에는 해당 주소로 리졸브되는 호스트 이름도 포함되며, 호스트 이름을 명시적으로 허용 목록에 추가하지 않는 한 차단됩니다. 로컬 개발 서버는 합법적인 예외이며, 하나씩 이름을 지정합니다.

빠른 시작

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

CDP가 활성화된 Chrome을 준비하세요(다음 중 하나):

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

Claude Code에 연결:

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

그런 다음 에이전트에게 *"localhost:5173의 히어로 섹션을 스크린샷 찍어줘 — .hero만 — 그리고 무엇이 이상한지 알려줘"*와 같은 요청을 하세요: selector는 하나의 요소로 크롭하여, 에이전트의 주의(와 토큰)를 4,000px 페이지 대신 논의 중인 부분에 집중시킵니다.

도구

설계 노트

• 샷마다 새로운 컨텍스트, 브라우저는 수명 동안 공유. 컨텍스트는 저렴하고 격리되어 있으며(쿠키, 캐시, 뷰포트), 브라우저는 비싸고 공유됩니다. CDP 연결에서 browser.close()는 원격 브라우저를 종료하지 않고 연결을 끊습니다 — 서버는 Chrome을 건드리지 않고 하루 종일 재시작할 수 있습니다.

• DNS는 확인되며, 리바인딩은 문서화됩니다. IP가 아닌 호스트 이름은 리졸브되고 반환된 모든 주소는 사설 범위에 대해 재확인됩니다. 브라우저 자체의 두 번째 리졸브에서 다르게 응답하는 악성 DNS 서버(고전적인 리바인딩)는 스크린샷 도구의 범위를 벗어납니다 — 얼버무리지 않고 여기에 명시합니다.

• deviceScaleFactor: 2 — 레티나 캡처, 에이전트(와 사람)가 스크린샷에서 흐릿한 텍스트를 생각보다 자주 잘못 읽기 때문입니다.

• 정책은 폐쇄 실패(fail-closed) 방식이며 테스트 가능합니다. evaluateUrl은 전체 위협 테이블이 테스트 파일에 있는 순수 함수입니다; 서버는 정책이 승인하기 전에 브라우저를 호출하지 않습니다.

스택

TypeScript · @modelcontextprotocol/sdk (stdio) · playwright-core (CDP 클라이언트 전용 — 번들 브라우저 없음) · zod · vitest.

라이선스

MIT © Brandon Ta