Auto Chrome MCP

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

설치 — 한 줄

Windows (PowerShell):

irm https://raw.githubusercontent.com/cw02326/auto-chrome-mcp/main/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/cw02326/auto-chrome-mcp/main/install.sh | bash

스크립트가 대신 해주는 것:

• ✅ 브리지 전역 설치 (npm install -g auto-chrome-mcp-bridge)

• ✅ Native Messaging manifest 등록 + doctor --fix 자동 점검

• ✅ 클로드 코드에 chrome-mcp-stdio 등록 (전역 — 어느 폴더에서 실행해도 사용 가능)

• ✅ 최신 릴리스에서 확장 zip 내려받아 압축 해제 (+ 윈도우는 폴더와 chrome://extensions 자동 열기)

Node.js 20+ 필요 — node -v 로 확인.

남은 2단계 — 여기서부터는 사람이 해야 합니다

1. 크롬 확장 로드 (자동화 불가)

chrome://extensions → 우측 상단 개발자 모드 ON → 압축해제된 확장 프로그램을 로드 → 설치 스크립트가 열어 준 폴더 선택.

크롬 정책상 chrome://extensions 는 스크립트로 조작할 수 없습니다. AI 도, 이 확장 자신도 대신 눌러 줄 수 없습니다. 반드시 사람이 클릭해야 하는 유일한 단계입니다.

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

2. 클로드 코드 재시작

껐다 켠 뒤 /mcp 입력 → chrome-mcp-stdio 가 보이면 성공입니다.

도구 목록은 MCP 서버가 시작할 때 한 번만 광고됩니다. 재시작 전에는 새 도구가 안 보입니다.

Related MCP server: BrowserMCP

설치 — 직접 하고 싶다면

npm install -g auto-chrome-mcp-bridge

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

• ✅ Native Messaging manifest 등록 (com.autochromemcp.nativehost)

• ✅ 확장 zip 다운로드 → ~/Downloads/auto-chrome-mcp-extension-v<version>/

• ✅ 클로드 코드가 설치돼 있으면 (~/.claude/ 존재) 트러블슈팅 스킬도 설치 → ~/.claude/skills/auto-chrome-mcp-doctor/SKILL.md. 이후 "MCP 안 돼" 한 마디로 자동 진단·복구. (이 스킬은 문제 해결용입니다 — 설치 수단이 아닙니다.)

그 다음 클로드 코드에 등록:

# macOS / Linux
claude mcp add --scope user --transport stdio chrome-mcp-stdio \
  -e CHROME_PORT=12320 -- node "$(npm root -g)/auto-chrome-mcp-bridge/dist/mcp/mcp-server-stdio.js"

# Windows PowerShell
claude mcp add --scope user --transport stdio chrome-mcp-stdio `
  -e CHROME_PORT=12320 -- node "$((npm root -g).Trim())\auto-chrome-mcp-bridge\dist\mcp\mcp-server-stdio.js"

마지막으로 위의 남은 2단계(확장 로드 + 클로드 코드 재시작)를 진행하면 됩니다.

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

이 저장소 주소만 받고 설치를 맡은 AI 에이전트라면

사람이 "이 링크 보고 설치해줘" 라고 했다면, 순서는 이렇습니다:

1. 위 한 줄 설치 스크립트를 실행한다 (OS 에 맞는 쪽).

2. 확장 로드는 대신 해줄 수 없다. 위 1단계를 사람에게 그대로 안내하고 기다린다 — chrome://extensions 는 스크립트·자동화가 접근할 수 없다.

3. 사람이 확장을 로드했다고 하면, 클로드 코드 재시작을 안내한다. 재시작 전에는 도구가 안 보인다.

4. 확인: auto-chrome-mcp-bridge doctor 가 모든 항목 OK 인지 본다 (12개 이상 — 설치된 브라우저 수와 OS 에 따라 늘어난다). Connectivity 만 실패하면 크롬이 꺼져 있거나 확장이 아직 로드되지 않은 것이다.

무간섭 모드 (v1.9.0 기본값)

기본 설정 그대로 쓰면 MCP 가 브라우저를 쓰는 동안 사용자 화면은 아무것도 바뀌지 않는다.

• MCP 작업 탭은 사용자 창이 아니라 별도의 MCP 작업 창 에 모인다. 그 창은 만들어진 직후 최소화돼 바탕화면 작업 영역에 나타나지 않는다(작업 표시줄에는 남는다).

• 탭 활성화(tabs.update({active:true}))는 그 전용 창 안에서만 일어난다. 사용자가 보고 있는 탭은 어떤 도구도 앞으로 끌어내지 않는다.

• OS 창 포커스는 기본적으로 가져오지 않는다. 창을 만들 때 포커스가 딸려오면 되돌려 놓는다.

• MCP 작업 탭은 창마다 하나씩 있는 초록색 탭 그룹 "MCP" 로 묶여, 사용자가 직접 연 탭과 탭 스트립에서 바로 구분된다(팝업의 "작업 탭 그룹 표시" 토글로 끌 수 있다). 편입은 탭을 활성화하거나 창 포커스를 바꾸지 않는다.

• 스크린샷·읽기·클릭·입력은 전부 보이지 않는 탭에서 정상 동작한다(CDP 경로).

그래도 방해받는다면 확장 팝업에서 두 가지를 확인한다.

1. 강제 포커스. 켜져 있으면 도구 실행 때 크롬 창이 앞으로 나온다. 끄면 된다.

2. 전용 작업 창. 기본은 꺼짐이다. 꺼져 있으면 사용자가 보고 있는 창에 백그라운드 탭을 만든다(탭은 활성화하지 않지만 탭 목록이 늘어난다). 켜면 MCP 작업 탭이 별도 창으로 분리된다.

저장된 설정은 기본값보다 우선한다. 예전 버전에서 전용 작업 창을 켰던 사용자는 팝업의 "무간섭 권장 설정으로 되돌리기" 버튼으로 한 번에 권장값(현재 창에 새 탭)으로 맞출 수 있다.

사용자 화면을 실제로 바꾸는 예외 도구는 셋뿐이다. 정의상 사용자 대면 동작이라 게이트를 타지 않는다: chrome_switch_tab(탭을 앞으로 가져오라는 요청 자체), chrome_request_element_selection (화면에서 요소를 고르게 함), chrome_request_user_consent(동의 창).

산출물 저장 위치와 자동 정리

스크린샷·GIF·PDF·성능 트레이스는 전부 한 곳에만 쌓인다.

Downloads/mcp-screenshots/YYYY-MM-DD/<종류>_<이름>_<HHmmss>.<확장자>

날짜와 시각은 로컬 시간이다. 사용자가 filename 에 폴더 경로를 넣어도 마지막 이름만 쓰므로 이 폴더 밖으로는 저장되지 않는다. 같은 이름이 겹치면 크롬이 알아서 번호를 붙인다.

보관 기간이 지난 날짜 폴더는 브리지가 시작할 때 자동으로 정리된다. 기본값은 7일이 지나면 보관 폴더로 옮기는 것이고, 설정은 ~/.auto-chrome-mcp/config.json 에 둔다(파일이 없으면 기본값).

{
  "artifactArchiveDir": "C:/PROJECTS/_작업물",
  "artifactRetentionDays": 7,
  "artifactCleanup": "archive"
}

• artifactCleanup: archive(기본, 보관 폴더로 이동) · delete(삭제) · off(정리 안 함)

• artifactRetentionDays: 며칠이 지나면 정리할지. 기본 7. 정확히 7일 된 폴더도 대상이다.

• artifactArchiveDir: 옮겨 둘 곳. 기본은 ~/auto-chrome-mcp-archive. 실제 이동 위치는 <보관 폴더>/YYYY-MM/YYYY-MM-DD/ 이고, 같은 이름이 있으면 접미사가 붙는다.

정리 대상은 mcp-screenshots 아래 날짜 이름 폴더 안의 일반 파일 뿐이다. 그 밖의 파일, 하위 폴더, 심볼릭 링크는 건드리지 않는다. 직접 돌려 보려면:

auto-chrome-mcp-bridge artifacts            # 무엇이 정리될지만 보여준다 (변경 없음)
auto-chrome-mcp-bridge artifacts --now      # 실제로 정리한다

마지막 실행 결과는 ~/.auto-chrome-mcp/artifacts-last-run.json 에 남는다.

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

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

민감 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?

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

진단 / 트러블슈팅

설치가 꼬였다면:

auto-chrome-mcp-bridge doctor          # 상태 점검 (12개 이상, 브라우저 수·OS 에 따라 늘어남)
auto-chrome-mcp-bridge doctor --fix    # 자동 복구
auto-chrome-mcp-bridge report --copy   # 진단 리포트 (이슈 등록용)

브리지는 시작할 때 로컬 HTTP 인증 토큰을 ~/.auto-chrome-mcp/auth-token 에 (소유자만 읽기) 만들고, MCP stdio 프록시가 그 파일을 읽어 인증한다. 이 파일이 없거나 남에게 읽히면 doctor 의 "Bridge auth token" 항목이 알려 준다. 지우면 브리지가 다음 시작 때 새로 만든다.

옛 확장 + 새 브리지 조합에서는 팝업의 강제 재연결이 401 이 나므로 확장도 함께 올려야 한다. 확장은 브리지가 네이티브 메시지로 넘겨준 토큰을 붙여야 /admin/* 과 /mcp 를 쓸 수 있다.

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/DAILY-AUTOMATION-ko.md

• 강제 재연결 동작 → docs/FORCE_RECONNECT.md

• 회귀 케이스 → docs/REGRESSION_CASES.md

• Playwright 폴백 → docs/PLAYWRIGHT_FALLBACK.md

License

원본 MIT — LICENSE.