Chrome Browser MCP

데스크톱 Google Chrome에 이미 열려 있는 탭을 비공개 ChatGPT 개발자 모드 앱이 검사하고 제어할 수 있게 해주는 로컬 브리지입니다.

현재 패치 버전: 0.1.2. 모든 패치는 이 버전을 올려야 하며, 그렇지 않은 패치는 CI에서 거부됩니다.

이 브리지는 17개의 MCP 도구를 제공합니다:

• 읽기: browser_status, list_tabs, get_active_tab, read_tab, read_tabs, search_tabs

• 동작: click, type, fill_form, press_key, scroll, select_option, navigate, new_tab, close_tab

• ChatGPT 하위 에이전트: spawn_chatgpt_agent, read_chatgpt_agent

spawn_chatgpt_agent는 기본적으로 백그라운드에서 새 chatgpt.com 탭을 열고, 사용자가 제공한 프롬프트를 정확히 그대로 제출한 다음 해당 탭 ID를 반환합니다. read_chatgpt_agent는 일반 탭에 사용되는 것과 동일한 제한된 의미론적 추출기를 통해 해당 하위 탭을 읽습니다. 하위 탭이 여전히 생성 중이면 나중에 다시 호출하세요.

동작 대상은 CSS 선택자 또는 정확한 표시 텍스트 / aria-label / placeholder / name / 연결된 레이블 텍스트를 허용합니다. 모호한 대상은 추측하는 대신 실패합니다.

이 브리지는 쿠키, 로컬 저장소, 세션 저장소, 저장된 비밀번호, 숨겨진 입력 값, 임의 JavaScript 실행, Chrome 내부 페이지 또는 시크릿 탭을 노출하지 않습니다. 또한 Chrome 디버거 API를 사용하지 않습니다.

검증된 경로

엔드투엔드 테스트는 압축 해제된 Manifest V3 확장 프로그램과 함께 실제 Chromium 프로세스를 실행하고, 실제 네이티브 메시징 호스트를 시작하며, Streamable HTTP를 통해 MCP 클라이언트를 연결하고, 실시간 페이지를 열고 나열하고 읽은 다음 비밀번호 입력 값이 반환되지 않는지 확인합니다. 유닛/통합 테스트 범위는 페이지 동작, MCP 라우팅, ChatGPT 하위 에이전트 도구 등록/구성, 생성된 확장 프로그램 버전 동기화, 그리고 Chrome/네이티브 메시징에서 사용하는 런타임 파일이 Git에 추적되는지 여부를 검증합니다.

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

모든 게이트를 실행하세요:

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

아키텍처

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

확장 프로그램이 연결되면 Chrome이 네이티브 호스트를 시작합니다. 네이티브 호스트는 루프백 MCP 엔드포인트를 시작합니다. 따라서 ChatGPT가 이 앱을 사용할 때마다 Chrome이 열려 있어야 하고 확장 프로그램이 활성화되어 있어야 합니다.

요구 사항

• macOS

• Google Chrome 120+

• Node.js 20+

• 개발자 모드를 사용할 수 있는 ChatGPT 계정

• Tunnels Read + Use 권한이 있는 OpenAI Platform 터널 ID 및 런타임 API 키

• tunnel-client

1. 네이티브 호스트 설치 및 확장 프로그램 1회 로드

npm run install:mac

이렇게 하면 네이티브 호스트 매니페스트가 다음 위치에 설치됩니다:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

그런 다음:

1. chrome://extensions를 엽니다.

2. 개발자 모드를 활성화합니다.

3. 압축 해제된 확장 프로그램 로드를 클릭합니다.

4. 이 저장소의 dist/extension 디렉터리를 선택합니다.

5. 확장 프로그램 ID가 정확히 다음과 같은지 확인합니다:

jlpddlfiallighiohmhhkemgbhofpnha

ID가 다르면 진행하지 마세요. 네이티브 호스트는 해당 정확한 확장 프로그램 출처만 허용합니다.

2. 향후 패치 업데이트

확장 프로그램 디렉터리는 한 번만 선택합니다. dist/ 아래의 빌드된 확장 프로그램과 MCP 브리지는 Git에 커밋되며, CI는 커밋된 런타임 빌드가 오래된 소스 변경을 거부합니다.

이후 모든 패치에 대해 일반적인 업데이트 흐름은 정확히 다음과 같습니다:

git pull

그런 다음 chrome://extensions를 열고 업데이트를 클릭합니다. 확장 프로그램 경로를 다시 선택하지 말고, 게시된 패치를 적용하기 위해 별도의 빌드 명령을 실행하지 마세요.

git pull은 dist/extension(Chrome이 로드하는 것)과 dist/bridge(네이티브 호스트가 실행하는 것)를 모두 업데이트합니다. 업데이트를 클릭하면 압축 해제된 확장 프로그램/네이티브 메시징 연결이 다시 로드되어 새로 가져온 런타임이 사용됩니다.

표시되는 확장 프로그램 버전은 모든 패치에서 변경되어야 합니다. 이 패치에서는 0.1.2로 표시되어야 합니다. 여전히 이전 버전이 표시된다면 가져온 런타임이 적용되지 않은 것입니다.

3. 로컬 브라우저 체인 확인

Chrome을 열어 둔 상태에서 다음을 실행하세요:

npm run verify:local

확인에 성공하면 다음이 출력됩니다:

• 확장 프로그램 ID

• 확장 프로그램 버전

• MCP 서버 버전

• 공개된 17개의 MCP 도구

확장 프로그램과 MCP 버전이 다르거나, 브리지가 너무 오래되어 MCP 버전을 보고하지 않으면 검증이 실패합니다. 이를 통해 오래된 15개 도구 브리지를 오래된 Chrome 확장 프로그램과 즉시 구분할 수 있습니다.

4. 보안 MCP 터널 구성

OpenAI Platform에서 터널과 런타임 API 키를 생성하세요. 그런 다음:

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

프로필은 터널을 다음으로 전달합니다:

http://127.0.0.1:2091/mcp

ChatGPT가 브라우저 도구를 필요로 할 때마다 tunnel-client run을 실행 중인 상태로 유지하세요.

5. ChatGPT에 추가

1. ChatGPT에서 설정 -> 보안 및 로그인 -> 개발자 모드를 활성화합니다.

2. 설정 -> 플러그인을 엽니다.

3. **+**를 클릭하여 개발자 모드 앱을 생성합니다.

4. 연결 유형으로 터널을 선택합니다.

5. 터널 ID를 선택하거나 붙여넣습니다.

6. app-metadata.json의 메타데이터를 사용합니다.

7. ChatGPT가 17개 도구를 모두 발견하는지 확인합니다.

8. 새 채팅에서 + -> 더 보기를 클릭하고 Chrome Browser를 선택한 다음 List my open Chrome tabs.라고 요청합니다.

정확한 검증 및 문제 해결 방법은 docs/CHATGPT_SETUP.md를 참조하세요.

보안 모델

웹페이지 텍스트는 데이터이지 권위가 아닙니다. 모든 콘텐츠 결과에는 명시적인 신뢰할 수 없는 콘텐츠 표시가 포함되며, 도구 지침은 모델이 페이지에서 발견한 지침을 동작으로 전환하지 말 것을 지시합니다.

확장 프로그램은 일반 열린 탭을 읽고 상호 작용할 수 있도록 의도적으로 모든 HTTP 및 HTTPS 페이지에 대한 액세스를 요청합니다. 보호 경계는 다음과 같습니다:

• 확장 프로그램은 사용자가 로컬에서 로드합니다;

• Chrome은 허용 목록에 정확히 등록된 네이티브 호스트만 시작합니다;

• 네이티브 호스트는 고정 확장 프로그램 ID를 제외한 모든 출처를 거부합니다;

• MCP 엔드포인트는 127.0.0.1에만 바인딩됩니다;

• 터널은 아웃바운드 전용입니다;

• 동작은 일반 HTTP(S) 탭으로 제한되며 임의 JavaScript, 디버거 액세스, 쿠키 또는 브라우저 저장소를 노출하지 않습니다;

• 모호한 사람이 읽을 수 있는 대상은 추측하는 대신 거부됩니다.

무인 사용 전에 THREAT_MODEL.md 및 SECURITY_REVIEW.md를 읽으세요.

알려진 제한 사항

• 한 번에 하나의 Chrome 프로필만 확장 프로그램을 로드해야 합니다. 두 프로필이 포트 2091을 두고 경쟁할 수 있습니다.

• Chrome 내부 페이지, Chrome 웹 스토어 페이지, file:// 페이지 및 시크릿 탭은 읽거나 제어할 수 없습니다.

• 교차 출처 iframe은 탐색되지 않습니다.

• Canvas 전용 애플리케이션과 Chrome의 기본 PDF 뷰어는 의미론적 텍스트를 거의 반환하지 않을 수 있습니다.

• 추출기는 원시 HTML이 아닌 기본 문서의 표시 텍스트, 제목, 링크 및 설명을 반환합니다. URL 자격 증명과 프래그먼트는 제거되며 민감한 쿼리 매개변수는 편집됩니다.

• press_key는 DOM 키보드 이벤트를 사용합니다. Enter 및 Escape는 명시적인 일반적인 동작을 제공하지만 일부 사이트에서는 신뢰할 수 있는 OS/CDP 키보드 입력이 필요합니다.

• ChatGPT 하위 에이전트 제출은 ChatGPT의 현재 웹 작성기(#prompt-textarea) 및 보내기 버튼 마크업에 따라 달라집니다. 향후 ChatGPT UI가 변경되면 해당 선택자를 업데이트해야 할 수 있습니다.

• read_chatgpt_agent는 하위 탭의 표시되는 의미론적 페이지 텍스트를 반환하며, 권한 있는 ChatGPT API 응답이 아닙니다.

• 파일 업로드는 일반적인 방식으로 구현하려면 더 강력한 파일 시스템/디버거 표면이 필요하기 때문에 의도적으로 구현되지 않았습니다.

개발

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit