mcp-chrome-scalemaker

hangwin/mcp-chrome 의 reliability fork — 5+ 개월 머지 안 된 핵심 PR 7개 흡수 + Force Reconnect + Diagnostic UI. stdio transport 강제 (HTTP 12306 안 씀). 웹스토어 등록 안 함 — npm + GitHub Release 사이드로드.

한 줄 설치

npm install -g mcp-chrome-scalemaker-bridge

postinstall 이 자동으로 처리하는 것:

• ✅ Bridge 전역 설치
• ✅ Native Messaging manifest 등록 (com.chromemcpscalemaker.nativehost)
• ✅ Extension zip 다운로드 → ~/Downloads/mcp-chrome-scalemaker-extension-v<version>/
• ✅ Claude Code 가 설치된 경우 (~/.claude/ 존재 시) troubleshooting 스킬도 자동 설치 → ~/.claude/skills/chrome-mcp-scalemaker-doctor/SKILL.md. 이후 "MCP 안 돼" 한 마디로 Claude 가 자동 진단·복구.

Node.js 20+ 필요 — node -v 로 확인. macOS / Windows / Linux 공통.

자동 스킬 설치를 원하지 않으면: SCALEMAKER_NO_SKILL=1 npm install -g mcp-chrome-scalemaker-bridge 사용자 custom 스킬 (frontmatter name 이 다른 경우) 은 절대 덮어쓰지 않음. 같은 스킬이 이미 있으면 scalemaker-version 비교 후 새 버전일 때만 갱신.

남은 단계 — 2개

1. Chrome 확장 로드

chrome://extensions 열기 → 우측 상단 Developer mode ON → "Load unpacked" 클릭 → ~/Downloads/mcp-chrome-scalemaker-extension-v<version>/ 선택.

Extension ID = aogfhfajjknomcnmlkbjmihjbknlhbbi (모든 사용자 동일 — manifest.key 박제로 unpacked load 시에도 allowed_origins 자동 일치).

2. Claude Code 에 등록

아래 prompt 를 복사 → 터미널의 claude 에 붙여넣기. Claude Code 가 .mcp.json 에 chrome-mcp-stdio 자동 등록.

지금 working dir (이 프로젝트 폴더) 의 .mcp.json 에 우리 chrome MCP (mcp-chrome-scalemaker) 를 등록해줘. ~/.claude.json 같은 전역 설정에는 손대지 마.

규칙:
- 이름: "chrome-mcp-stdio"
- transport: stdio (HTTP 안 씀)
- command: "node"
- args: ["<npm root -g 출력값>/mcp-chrome-scalemaker-bridge/dist/mcp/mcp-server-stdio.js"]
- env: { "CHROME_PORT": "12320" }

먼저 `npm root -g` 를 bash 로 실행해서 실제 경로 얻고, 그 다음에 working dir 의 .mcp.json (없으면 신설) 의 mcpServers.chrome-mcp-stdio 만 추가/갱신해줘. 기존 다른 server 항목은 보존.

등록이 끝나면 아래 절차도 함께 안내해줘:
1. Claude Code 를 Ctrl+C 두 번으로 종료 후 다시 실행 (mcp 서버 재로드)
2. `/mcp` 입력해서 chrome-mcp-stdio 가 connected 상태인지 확인
3. 확인 후 Esc 로 빠져나오기

등록 후 Claude Code 재시작 → /mcp 로 활성 확인.

⚠️ 사이트 권한 자동 허용 — 알아두세요

scalemaker 는 AI 자동화가 끊기지 않도록 Chrome 사이트 권한 prompt 를 자동으로 처리합니다 (v1.0.32+). 두 갈래로 동작:

권한	처리 시점	효과
Popups	install 시 모든 사이트 일괄	모든 사이트의 window.open() 차단 안 됨
Notifications	install 시 모든 사이트 일괄	알림 권한 prompt 안 뜸
Clipboard	install 시 모든 사이트 일괄	클립보드 읽기 prompt 안 뜸
Automatic downloads	install 시 모든 사이트 일괄	다중 파일 자동 다운로드 prompt 안 뜸
Camera	AI 사용 사이트만 누적 자동	Chrome 정책상 일괄 불가. AI 가 사용한 사이트만 그 origin 영구 허용 (sticky)
Microphone	AI 사용 사이트만 누적 자동	동일
Geolocation	AI 사용 사이트만 누적 자동	v1.0.32+ 부터 민감 처리로 이동 (OS 권한 + 개인정보 보호). camera/mic 와 동일 모델로 통일

민감 3종 작동 방식 (camera/microphone/geolocation): AI 가 카메라/마이크/위치 정보를 쓰려고 하면 popup 토글을 확인 → 토글 ON 이면 즉시 그 사이트만 origin 단위로 영구 허용 (chrome.contentSettings.X.set({primaryPattern:'https://example.com/*', setting:'allow'})). 한 번 set 된 사이트는 브라우저 재시작 후에도 prompt 안 뜸. 사용자가 직접 chrome://settings/content/{camera,microphone,location} 갈 필요 없음.

OS 레벨 권한은 사용자 직접 설정 필요:

• macOS: 시스템 설정 > 개인정보 보호 및 보안 > 카메라/마이크/위치 서비스 → Google Chrome 토글 ON
• Windows: 설정 > 개인 정보 보호 > 카메라/마이크/위치 → Chrome 허용
• (OS 권한이 꺼져 있으면 Chrome 확장이 아무리 허용해도 디바이스/위치 접근 자체가 안 됨)

AI 자동화 흐름 confirm 게이트: popup 하단 "권한 설정" 의 토글 3개 (camera/microphone/geolocation) 는 AI 가 해당 기능을 쓸 때마다 사용자 confirm 을 받을지 결정합니다.

• Default: 토글 3개 전부 ON (install 시 초기화). 묻지 않고 즉시 사용.
• OFF 로 내리면: AI 가 해당 기능 호출 시 작은 confirm 창이 떠서 허용 여부를 묻습니다 (60초 timeout).
• 끄려면: 확장 아이콘 클릭 → popup 하단 "권한 설정" 섹션에서 토글 OFF.

보안 모델 — 비민감 4종 (popups/notifications/clipboard/autoDownload) 은 install 시 모든 사이트 일괄 허용이라 일반 사용자에게 위험할 수 있음. 민감 3종 (camera/microphone/geolocation) 은 AI 가 방문한 사이트에만 누적 추가되므로 사용자가 신뢰하지 않는 사이트엔 영향 없음 (그 사이트에 가지 않으면 추가 안 됨). 별도 Chrome 프로필 사용을 권장합니다.

opt-out: 자동 권한 세팅을 원하지 않으면 설치 후 chrome://settings/content 에서 비민감 4종을 직접 default 로 되돌리세요. 민감 3종의 origin 별 누적 허용은 chrome://settings/content/{camera,microphone,location} 에서 사이트별로 삭제 가능.

왜 fork?

흡수한 upstream PR (5+ 개월 OPEN)	효과
#346 singleton transport 제거 → factory pattern	"已连接, 服务未启动" 노란불 해결 / 두 client 동시 연결 가능
#312 stale reconnect EOF handler	네트워크 잠시 끊김 후 자동 복구
#302 + #304 STDIO session/parent cleanup	parent 죽으면 zombie 0
#329 pagehide for Chrome 144+	144 업데이트 후 streamable HTTP error 해결
#338 partial (transport close cleanup)	memory leak 방지
#313 CHROME_MCP_HOST env	LAN 노출 / 포트 충돌 회피

Fork 신규	효과
⚡ 강제 재연결 5단계 슈퍼버튼	drain → port free → spawn → handshake → MCP ping 자동. 사용자 pkill 수동 작업 0
🔬 진단 리포트 + Self-Test	env / bridge process / Self-Test 5 케이스 / Copy as JSON
deterministic extension ID (manifest.key 박제)	모든 사용자 ID = aogfhfajjknomcnmlkbjmihjbknlhbbi → unpacked load 시에도 allowed_origins 자동 일치
stdio 강제 정책	HTTP 12306 안 씀. native messaging 기반 stdio 만
Claude design tokens (warm cream + coral)	popup UI = Anthropic Claude 디자인 시스템
한국어 patch	popup 의 UI 텍스트 한국어 (단축 도구·관리 메뉴 등 잡 기능은 제거)

(옵션) Chrome Launcher + Playwright CDP 폴백 — scalemaker-chrome CLI 가 Chrome 을 --remote-debugging-port=9222 로 띄움. native messaging 끊겨도 CDP attach 로 도구 미러. 일반 사용엔 불필요.

진단 / 트러블슈팅

설치가 꼬였다면:

mcp-chrome-scalemaker-bridge doctor          # 상태 점검
mcp-chrome-scalemaker-bridge doctor --fix    # 자동 복구
mcp-chrome-scalemaker-bridge report --copy   # 진단 리포트 (이슈 등록용)

Upstream sync

매주 자동 검사 (upstream-check.yml) + 월 1회 정기 sync. 흡수한 PR 이 upstream 머지되면 retire issue 자동 생성. 정책 → docs/UPSTREAM_SYNC.md

더 자세히

• 설계 → docs/DESIGN.md (33KB, 9 섹션)
• 흡수 PR 매트릭스 → UPSTREAM_DIFF.md
• 강제 재연결 동작 → docs/FORCE_RECONNECT.md
• 회귀 케이스 → docs/REGRESSION_CASES.md
• Playwright 폴백 → docs/PLAYWRIGHT_FALLBACK.md

License

원본 MIT — LICENSE.