MCP Browser

Model Context Protocol 서버로 작동하는 네이티브 macOS 웹 브라우저입니다. AI 에이전트가 사람이 사용하는 것과 동일한 방식으로 실제 WKWebView를 제어할 수 있습니다(탐색, 클릭, 양식 작성, DOM 읽기, 스크린샷 촬영, JavaScript 실행, 네트워크 및 콘솔 활동 캡처).

SwiftUI와 WKWebView로 구축되었습니다. MCP 서버는 베어러 토큰 인증 및 DNS 리바인딩 방어 기능을 갖춘 로컬 HTTP를 통해 프로세스 내에서 실행됩니다.

다운로드

⬇ 최신 macOS 빌드 다운로드 — Apple Silicon용으로 서명 및 공증된 .dmg 파일입니다.

다운로드 후 DMG를 열고 MCP Browser를 응용 프로그램 폴더로 드래그하세요.

스크린샷

MCP Browser 창

MCP Browser 도구 및 설정

개발 배경

에이전트를 위한 기존의 "도구로서의 브라우저" 방식은 크게 두 가지로 나뉩니다:

헤드리스 자동화(Playwright, Puppeteer) — 빠르고 스크립트 작성이 가능하지만, 에이전트가 사용자가 보는 화면을 볼 수 없고, 로그인 세션을 공유할 수 없으며, 사용자가 신뢰하는 브라우저 엔진과 다른 엔진에서 실행됩니다.
원격 제어 클라우드 브라우저 — 데이터가 기기 외부로 유출되며, 세션당 비용을 지불해야 합니다.

MCP Browser는 세 번째 대안입니다. 사용자가 직접 로그인하고 탐색하며 사용하는 Mac의 실제 브라우저 창을, 필요할 때 LLM이 MCP를 통해 제어할 수 있게 합니다. 쿠키, 기록, 북마크, 다운로드 파일은 모두 로컬에 유지됩니다. 에이전트는 사용자와 동일한 페이지를 보게 됩니다.

기능

브라우저

WKWebView 기반 탭, Safari 스타일의 탭 스트립(파비콘, 마우스 오버 시 닫기, 동일 너비 탭)
기록 및 북마크 자동 완성을 지원하는 URL 바
북마크 바, 전체 북마크 관리자, 기록 보기, 다운로드 팝오버
페이지 내 찾기, 호스트별 줌 설정 유지, 화면 속 화면(PiP) 컨트롤러
북마크 가져오기(HTML / Safari / Chrome 형식)
탭별 쿠키 및 네트워크 캡처

MCP 서버

로컬 HTTP 전송(포트 8833, 설정 가능) — JSON-RPC용 POST /mcp, SSE 스타일 상태 확인용 GET /mcp
베어러 토큰 인증 — 실행 시마다 토큰 생성, 설정에서 재생성 가능
DNS 리바인딩 방어 — 127.0.0.1 / localhost에 대해 Host 헤더 검증
자동 등록 — MCPRegistrar를 통해 일반적인 MCP 클라이언트(Claude Desktop, Codex 등)에 자동 등록
도구 작업 로그 — 모든 도구 호출은 인수, 결과 요약, 실행 시간과 함께 기록됨

도구(현재 카탈로그)

탐색 — navigate, back, forward, reload, current_url, current_title
탭 — list_tabs, new_tab, switch_tab, close_tab
DOM — click, fill, submit, hover, press_key, type_text, scroll, find_in_page, get_element, accessibility_tree
페이지 콘텐츠 — read_text, read_page, page_metadata, screenshot, pdf_export, render_html, eval_js, find, list_links, list_forms
쿠키 / 저장소 — get_cookies, set_cookie, storage, clear_session
북마크 — list_bookmarks, open_bookmark_folder
검사 — console_logs, network_log, dialog
파일 — download, upload_file(사용자 권한 필요)
기타 — wait_for, emulate, resize

공식 목록은 MCP Browser/MCP/MCPToolCatalog.swift를 참조하세요.

개인정보 보호 및 안전

실행 시마다 생성되는 베어러 토큰 — 토큰이 없는 클라이언트는 401 Unauthorized 응답을 받음
출처 / 호스트 검증 — 악의적인 로컬 웹 페이지로부터의 DNS 리바인딩 공격 차단
사용자 확인 — 다운로드, 업로드 및 모든 dialog 상호작용 시 사용자 확인 필요
기본적으로 로컬 전용 — 서버는 127.0.0.1에 바인딩되며, 공용 네트워크에는 절대 노출되지 않음
설정 내 작업 로그 — 에이전트가 브라우저에서 수행한 작업을 정확히 확인 가능

요구 사항

macOS 14 이상(Sonoma 이상)
소스 빌드 시 Xcode 16 이상

시작하기 (사용자)

Releases 페이지에서 최신 DMG를 다운로드합니다.
MCP Browser를 /Applications로 드래그하고 실행합니다.
Settings → Connection을 열어 베어러 토큰과 MCP 엔드포인트 URL을 복사합니다.
MCP 클라이언트(Claude Desktop, Codex 등)에 서버를 추가합니다. 앱의 Settings → MCP Clients 탭에서 일반적인 클라이언트에 대한 설정을 자동으로 패치할 수 있습니다.
평소처럼 브라우징합니다. LLM이 웹에서 작업을 수행해야 할 때 MCP를 통해 도구를 호출하며, 작업 로그에서 해당 내용을 확인할 수 있습니다.

시작하기 (개발자)

이 저장소를 복제합니다.
Xcode에서 MCP Browser.xcodeproj를 엽니다.
MCP Browser 스킴을 선택합니다.
My Mac에서 빌드하고 실행합니다.

CLI 빌드:

xcodebuild -project "MCP Browser.xcodeproj" -scheme "MCP Browser" -configuration Debug build

직접 포크하여 빌드하기

이 프로젝트는 원작자의 서명 설정이 포함되어 있습니다. 직접 빌드하고 배포하기 위해 포크하는 경우:

개발 팀 — Xcode에서 MCP Browser 타겟을 열고 Signing & Capabilities에서 본인의 팀을 선택합니다. 이는 MCP Browser.xcodeproj/project.pbxproj의 DEVELOPMENT_TEAM을 수정합니다.
번들 식별자 — PRODUCT_BUNDLE_IDENTIFIER를 com.moosia.mcp-browser에서 본인 소유의 식별자로 변경합니다.
API 키는 포함되어 있지 않습니다. MCP Browser는 LLM 제공업체를 직접 호출하지 않으며, 연결된 클라이언트에 도구만 제공합니다.

MCP 클라이언트 설정

대부분의 MCP 클라이언트는 HTTP 전송 블록을 허용합니다. claude_desktop_config.json 예시:

{
  "mcpServers": {
    "mcp-browser": {
      "transport": "http",
      "url": "http://127.0.0.1:8833/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-settings>"
      }
    }
  }
}

포함된 MCP Clients 설정 탭에서 지원되는 클라이언트(Claude Desktop, Codex 등)에 대해 이 설정을 자동으로 작성할 수 있습니다. 클라이언트를 선택하고 Add MCP Browser를 누르면 파일이 자동으로 패치됩니다.

토큰은 Settings → Connection에서 Regenerate token을 클릭할 때마다 변경됩니다. 토큰 재생성 후에는 클라이언트 설정을 다시 패치해야 합니다.

데이터 저장

북마크, 기록, 호스트별 줌 설정, 다운로드 및 작업 로그는 PersistentStore(파일 기반)와 필요한 경우 SwiftData를 사용하여 로컬에 저장됩니다.
베어러 토큰은 UserDefaults에 저장됩니다. 기존 클라이언트의 권한을 취소하려면 Settings → Connection에서 언제든지 재생성할 수 있습니다.
파비콘은 Application Support 내 디스크에 캐시됩니다.
텔레메트리나 클라우드 동기화는 없습니다. 사용자가 호출하는 MCP 도구에 의해 발생하는 경우를 제외하고는 기기 외부로 데이터가 나가지 않습니다.

프로젝트 구조

MCP Browser/
├── Browser/         WKWebView wrapper, tab model, presenter, scripts, PiP
├── MCP/             MCP server, JSON-RPC, host protocol, tool catalog
│   ├── Registrar/   Auto-config patcher for Claude Desktop / Codex / etc.
│   └── Tools/       Tool implementations (navigation, DOM, content, etc.)
├── Settings/        Settings tabs (general, privacy, connection, recorder, etc.)
├── Storage/         Bookmarks, history, downloads, favicons, action log
├── Views/           Bookmarks bar, bookmarks manager, history, downloads popover
├── ContentView.swift     Top-level window layout, tab strip, URL bar
├── AppCommands.swift     Menu bar commands and keyboard shortcuts
└── MCP_BrowserApp.swift  App entry point and environment wiring

주요 파일

MCP/MCPServer.swift — NWListener 기반 HTTP/JSON-RPC 서버, 인증, 리바인딩 방어
MCP/MCPCoordinator.swift — 도구 호출을 포커스된 창의 활성 탭으로 라우팅
MCP/MCPToolCatalog.swift — 노출된 모든 도구의 레지스트리
MCP/MCPSecret.swift — 키체인 기반 베어러 토큰
Browser/BrowserTab.swift — WKWebView를 래핑하는 탭별 @Observable 모델
Browser/WebViewHost.swift — NSViewRepresentable 브리지

보안 모델

MCP Browser는 의도적으로 샌드박스 없이 실행되므로 다음 작업이 가능합니다:

~/Library/Application Support / ~/.config 내의 MCP 클라이언트 설정 파일 패치
명시적으로 요청된 경우 다른 앱 제어(예: 외부 스킴 열기)

다음 작업은 수행하지 않습니다:

루프백(127.0.0.1) 이외의 네트워크 인터페이스 바인딩
실행 시마다 생성되는 베어러 토큰 없이 연결 수락
Host 헤더가 127.0.0.1 또는 localhost와 일치하지 않는 요청 처리(DNS 리바인딩 방어)
자체적으로 기기 외부로 데이터 전송

감사가 필요한 경우, 전체 HTTP 인터페이스는 MCP Browser/MCP/MCPServer.swift에 있으며 약 400줄 정도입니다.

알려진 제한 사항

작업 로그는 아직 UI에서 소급 검색할 수 없습니다.
다중 창 지원은 가능하지만, MCP 코디네이터는 가장 최근에 포커스된 창으로만 라우팅합니다.
사이트의 OAuth 및 기본 인증 흐름은 WebKit에서 처리하며, MCP Browser 자체는 비밀번호를 저장하지 않습니다. 현재는 Safari/Chrome 가져오기를 통해 시스템 키체인을 사용하세요.
모바일/iOS 빌드는 지원하지 않으며, Mac 전용 도구입니다.

기여

버그 신고, 기능 요청 및 풀 리퀘스트 제출 방법은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT

mcp-browser