iOS WebKit Debug Proxy MCP Server + CLI
CI
Lint
Go Report Card
License: MIT
Install in Claude Code
Install in VS Code
Install in VS Code Insiders
Install in Cursor
Install in Windsurf
Install in Codex
Install in Antigravity
Install in JetBrains
AI 에이전트로부터 iOS Safari를 디버깅하세요. 기존 도구 중에는 AI 어시스턴트가 실제 iPhone의 Safari와 상호 작용할 수 있는 것이 없습니다. Chrome DevTools MCP는 CDP(Chrome DevTools Protocol)를 사용하며, 이는 WebKit과 호환되지 않습니다. 이 프로젝트가 그 격차를 해소합니다.
<video src="https://github.com/user-attachments/assets/dcc0dc05-3a1f-4454-88a8-51ee28da9fd2" poster="https://github.com/user-attachments/assets/3901f7ff-6531-4866-b49e-cf5d17304327" autoplay loop muted playsinline></video>
27개 WebKit Inspector Protocol 도메인 전반에 걸쳐 100가지 이상의 도구 제공 — 네비게이션, 스크린샷, DOM 검사, CSS, 네트워크 가로채기(interception), httpOnly 쿠키, JS 디버깅, 힙 스냅샷, 프로파일링 등. MCP 서버와 CLI 간의 기능 동등성(feature parity)을 완벽하게 구현했습니다.
왜 필요한가요?
- Chrome DevTools MCP는 데스크톱 Chrome용으로 존재합니다. 하지만 iOS Safari를 위한 것은 없었습니다 — 바로 지금까지는요.
document.cookie로는 볼 수 없는 httpOnly 쿠키도 이 도구를 통해 프로토콜을 이용해 읽을 수 있습니다.
- **실제 기기 테스트(Real device testing)**는 시뮬레이터가 놓치는 iOS 전용 버그를 잡아냅니다.
- Claude Code, VS Code, Cursor, Windsurf, Codex CLI, Antigravity, JetBrains 및 모든 MCP 호환 클라이언트와 작동합니다.
설치 방법
필수 조건 (Prerequisites)
brew install ios-webkit-debug-proxy
...
Linux 및 기타 플랫폼의 경우, ios-webkit-debug-proxy 설치 가이드를 참조하십시오.
Claude Code 플러그인 (권장)
Claude Code 내부에서 다음을 실행합니다:
/plugin marketplace add nnemirovsky/iwdp-mcp
/plugin install iwdp-mcp
Go 설치
go install github.com/nnemirovsky/iwdp-mcp/cmd/...@latest
사전 빌드 바이너리 (Pre-built Binaries)
GitHub Releases에서 다운로드하십시오.
소스 코드로부터 빌드 (Build from Source)
git clone https://github.com/nnemirovsky/iwdp-mcp.git
cd iwdp-mcp
make build
빠른 시작 (Quick Start)
CLI
ios_webkit_debug_proxy --no-frontend &
...
MCP 서버
<details id="claude-code">
<summary><strong >Claude Code</strong></summary>
플러그인으로 설치 (권장):
/plugin marketplace add nnemirovsky/iwdp-mcp
/plugin install iwdp-mcp
또는 프로젝트의 .mcp.json에 추가:
{
"mcpServers": {
"iwdp-mcp": {
...
또는 CLI를 통해:
claude mcp add iwdp-mcp -- iwdp-mcp
</details>
<details>
<summary><strong >Claude Desktop</strong></summary>
~/Library/Application Support/Claude/claude_desktop_config.json에 추가:
{
"mcpServers": {
"iwdp-mcp": {
...
</details>
<details>
<summary><strong >VS Code / VS Code Insiders</strong></summary>
이 README 상단의 설치 배지를 클릭하거나, .vscode/mcp.json에 추가:
{
"servers": {
"iwdp-mcp": {
...
또는 CLI를 통해:
code --add-mcp '{"name":"iwdp-mcp","command":"iwdp-mcp"}'
</details>
<details>
<summary><strong >Cursor</strong></summary>
이 README 상단의 Cursor 설치 배지를 클릭하거나, .cursor/mcp.json에 추가:
{
"mcpServers": {
"iwdp-mcp": {
...
</details>
<details id="windsurf">
<summary><strong >Windsurf</strong></summary>
~/.codeium/windsurf/mcp_config.json에 추가:
{
"mcpServers": {
"iwdp-mcp": {
...
</details>
<details id="codex-cli">
<summary>
<strong>Codex CLI</strong>
</summary>
codex mcp add iwdp-mcp -- iwdp-mcp
또는 ~/.codex/config.toml에 추가합니다:
[mcp_servers.iwdp-mcp]
command = "iwdp-mcp"
</details>
<details id="antigravity">
<summary>
<strong>Antigravity</strong>
</summary>
~/.gemini/antigravity/mcp_config.json에 추가합니다:
{
"mcpServers": {
"iwdp-mcp": {
...
</details>
<details id="jetbrains-ides">
<summary>
<strong>JetBrains IDEs</strong>
</summary>
**설정(Settings) → 도구(Tools) → AI Assistant → Model Context Protocol (MCP) → 추가(Add)**로 이동하거나, 다음 JSON 설정을 추가합니다:
{
"mcpServers": {
"iwdp-mcp": {
...
</details>
예시 프롬프트
MCP 서버가 구성되면, 다음과 같은 내용을 AI 어시스턴트에게 요청할 수 있습니다:
시작하기 (Getting started)
Connect to my iPhone's Safari and show me what tabs are open
Take a screenshot of the current page
What's the page title and URL?
JavaScript 및 DOM
Run document.querySelectorAll('a') and list all links on the page
Find all elements with class "error" and show their text content
Get the full DOM tree of the page
...
CSS 및 스타일 (CSS & Styles)
What CSS rules are applied to the header element?
Show me the computed styles for the main content area
Force the :hover state on the dropdown menu
...
네트워크 (Network)
Monitor network requests while I interact with the page
Show me the response body of that failed API call
Intercept all requests to api.example.com and log them
...
저장소 및 쿠키 (Storage & Cookies)
Show me all cookies including httpOnly and secure ones
Set a session cookie named "debug" with value "true"
Delete the authentication cookie
...
디버깅 (Debugging)
Set a breakpoint in main.js at line 42
Pause execution and show me the call stack
Step through the code and show variable values
...
성능 및 프로파일링 (Performance & Profiling)
앱을 탐색하는 동안 타임라인 기록 시작
힙 스냅샷을 찍고 잠재적인 메모리 누수 찾기
이 애니메이션이 실행되는 동안 CPU 사용량 프로파일링
...
고급 기능 (Advanced)
컴포지팅 레이어 전체 목록 및 컴포지션 이유 표시
페이지의 모든 활성 CSS 애니메이션 표시
캔버스 내용을 이미지로 캡처
...
작동 방식 (How It Works)
┌────────────┐ USB ┌──────────┐ HTTP/WS ┌──────────┐
│ iOS 장치 │◄──────────►│ iwdp │◄────────────►│ iwdp-mcp │
│ (Safari) │ │ :9221-N │ │ 또는 CLI │
...
ios-webkit-debug-proxy가 노출하는 기능:
- 포트 9221 — 연결된 모든 장치 목록 표시
- 포트 9222 이상 — 각 장치는 증가된 포트를 할당받으며 Safari 탭을 나열함
- 각 탭은 WebKit Inspector Protocol용 WebSocket URL을 제공합니다.
iwdp-mcp는 이러한 WebSocket 엔드포인트에 연결하여 100가지 이상의 도구를 노출합니다.
핵심 기능 (Core)
| 도구 | 설명 |
|---|
iwdp_status | ios-webkit-debug-proxy 확인/자동 시작 |
| ... | |
DOM 및 CSS (DOM & CSS)
get_outer_html, get_attributes, get_event_listeners, highlight_node, get_matched_styles, get_computed_style, set_style_text, force_pseudo_state 등.
네트워크 (Network)
network_enable, list_network_requests, get_response_body, set_request_interception, intercept_continue, intercept_with_response, set_emulated_conditions, set_resource_caching_disabled.
스토리지 (Storage)
get_cookies (httpOnly + secure), set_cookie, delete_cookie, get_local_storage, get_session_storage, list_indexed_databases, get_indexed_db_data.
디버깅 (Debugging)
debugger_enable, set_breakpoint, pause, resume, step_over, step_into, step_out, get_script_source, evaluate_on_call_frame, set_pause_on_exceptions.
timeline_start/stop, memory_start/stop_tracking, heap_snapshot, cpu_start/stop_profiling, script_start/stop_profiling.
추가 기능
애니메이션(Animation), 캔버스(Canvas), 레이어트리(LayerTree), 워커(Workers), 감사(Audit), 보안(Security) (TLS 인증서), 그리고 요소 상호작용(click, fill, type_text)을 지원합니다.
개발
make build
make test
make test-e2e
...
테스트
단위 테스트(Unit tests)는 WebKit Inspector Protocol을 시뮬레이션하는 모의 WebSocket 서버(internal/webkit/testutil/)를 사용합니다. E2E 테스트는 iOS Simulator를 부팅하고 실제 Safari를 대상으로 모든 도구를 실행합니다.
참고: E2E 테스트에는 Xcode와 ios-webkit-debug-proxy가 설치된 macOS가 필요합니다. GitHub Actions의 macos-latest 러너는 Xcode와 iOS Simulator 런타임이 사전 설치되어 있습니다.
프로젝트 구조
iwdp-mcp/
├── cmd/
│ ├── iwdp-mcp/ # MCP 서버 (stdio 전송)
...
라이선스
MIT — LICENSE 참조.
ios-webkit-debug-proxy는 BSD-3-Clause 라이선스가 적용된 별도의 프로젝트입니다. 이 도구는 코드를 번들링하지 않고 런타임에 HTTP/WebSocket을 통해 해당 프로젝트와 연결됩니다.