# MCP

Claude Code, Codex, Cursor 등 MCP 클라이언트를 Device MCP에 연결하면 AI 에이전트가 iPhone과 iPad에서 화면을 보고, 탭하고, 입력하고, 테스트할 수 있습니다.

Device MCP는 AI 코딩 에이전트를 실제 iPhone과 iPad에 연결합니다. 에이전트는 평소처럼 대화하는 것만으로 화면을 보고, 탭하고, 입력하고, 앱을 열고, 프로젝트를 빌드해 기기에서 테스트할 수 있습니다.

## 1. Device MCP의 MCP 서버란?
**MCP**(Model Context Protocol)는 AI 에이전트가 도구와 통신할 때 사용하는 개방형 표준입니다. Device MCP에는 MCP 서버가 내장되어 있어 Claude Code, Codex, Cursor 등 MCP를 지원하는 에이전트가 사용자와 똑같은 방식으로 기기를 조작할 수 있습니다.

서버는 Mac에서만 실행됩니다. 에이전트에게 보라고 요청한 것을 제외하면 화면과 앱은 Mac 밖으로 나가지 않습니다. [개인정보 보호 및 보안](../help/privacy-and-security.md)을 참고하세요.

### ✅ 프롬프트 예시
* 내 iPhone 스크린샷을 찍고 화면에 무엇이 있는지 알려 줘.
* 설정을 열고 다크 모드를 켜 줘.
* 내 앱을 빌드해서 iPad에서 실행하고 로그인 화면이 제대로 작동하는지 확인해 줘.
* 테스트 계정으로 로그인하고 장바구니에 상품을 담은 다음 합계 금액을 확인해 줘.
* 기기에서 앱이 크래시됐어. 크래시 리포트를 찾아서 버그를 고쳐 줘.
* `myapp://profile`을 열고 스크린샷을 찍어 줘.
* 온보딩 과정을 화면 기록해 줘.

## 2. 장점
| 장점 | 설명 |
| --- | --- |
| **실제 기기에서 테스트** | 에이전트가 실제 성능, 센서, 시스템 팝업을 그대로 갖춘 실제 iPhone이나 iPad에서 테스트합니다. |
| **폐쇄 루프 개발** | 수정, 빌드, 실행, 탭, 스크린샷, 버그 수정까지 에이전트가 사용자 없이 스스로 작업을 검증합니다. |
| **사용자와 같은 화면을 봅니다** | 에이전트가 화면의 텍스트와 버튼을 읽으므로 **로그인** 버튼을 이름으로 찾아 탭할 수 있습니다. |
| **통제권은 사용자에게** | 위험한 동작은 먼저 확인을 요청하고, 모든 동작이 기록되며, 언제든 직접 조작할 수 있습니다. |
| **사용하는 에이전트와 호환** | Claude Code, Codex, Cursor를 비롯한 모든 MCP 클라이언트와 함께 작동합니다. |

## 3. 에이전트에 Device MCP 추가하기
1. **MCP 서버 켜기**
   * **Device MCP → Settings → MCP**를 엽니다.
   * **Enable MCP Server**를 켭니다.
2. **에이전트용 설정 복사하기**: **Settings → MCP → MCP Configuration**에서 **Claude Code**, **Codex**, **Manual** 중 하나를 선택하고 **Copy**를 클릭합니다. Inspector의 **Agent** 탭에도 같은 설정이 있습니다.
3. 아래 단계에 따라 **에이전트에 추가합니다**.

### Claude Code
터미널에서 다음 명령어를 실행하세요.

```bash
claude mcp add --scope user device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp"
```

`--scope user`를 지정하면 모든 프로젝트에서 Device MCP를 사용할 수 있습니다.

### Codex
`~/.codex/config.toml`에 다음 내용을 추가하세요.

```toml
[mcp_servers.device-mcp]
command = "/Applications/Device MCP.app/Contents/MacOS/device-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 900
```

{% hint style="info" %}
앱을 빌드하고 사용자의 승인을 기다리는 데 몇 분이 걸릴 수 있습니다. `tool_timeout_sec`을 설정하면 Codex가 그동안 충분히 기다립니다.
{% endhint %}

### Cursor 및 기타 MCP 클라이언트
클라이언트의 MCP 설정에 다음 내용을 추가하세요.

```json
{
  "mcpServers": {
    "device-mcp": {
      "command": "/Applications/Device MCP.app/Contents/MacOS/device-mcp",
      "args": []
    }
  }
}
```

4. **Device MCP 사용 시작하기**
   * 기기를 연결한 상태로 Device MCP를 열어 둡니다.
   * 에이전트에게 요청해 보세요. 예: *"내 기기 목록을 보여 주고 스크린샷을 찍어 줘."*

{% hint style="warning" %}
에이전트가 MCP 서버가 꺼져 있다고 하면 **Device MCP → Settings → MCP**를 열고 **Enable MCP Server**를 켜세요. 에이전트를 사용하려면 [Device MCP Pro](../license.md)가 필요합니다.
{% endhint %}

## 4. 에이전트가 할 수 있는 일
| 영역 | 에이전트가 할 수 있는 일 |
| --- | --- |
| **기기** | 연결된 기기를 나열하고, 그중 하나를 선택하고, 세부 정보를 읽습니다. |
| **화면 보기** | 스크린샷을 찍고 화면의 텍스트와 버튼을 읽습니다. |
| **터치** | 탭, 텍스트를 찾아 탭, 두 번 탭, 길게 누르기, 스와이프, 스크롤, 핀치를 합니다. |
| **입력** | 텍스트를 입력하고, 키를 누르고, 키보드를 숨깁니다. |
| **시스템** | 홈, 잠금, 음량, Siri 버튼을 누르고, 제어 센터나 앱 전환기를 열고, 화면을 회전합니다. |
| **앱** | 앱을 나열, 실행, 종료, 설치, 제거하고 링크를 엽니다. |
| **Build & Run** | Xcode 프로젝트를 빌드하고 기기에서 실행합니다. [Build & Run](build-and-run.md)을 참고하세요. |
| **디버그** | 크래시 리포트를 읽고 앱 데이터를 다운로드합니다. |
| **화면 기록** | 화면 기록을 시작하고 중지합니다. |
| **사용자에게 요청** | Face ID나 암호 입력처럼 사용자가 직접 나서야 할 때 요청합니다. [Human Handoff](human-handoff.md)를 참고하세요. |

사용 중인 Device MCP 버전의 전체 도구 목록은 MCP 클라이언트에서 확인할 수 있습니다.

## 5. 통제권 유지하기
* **승인**: 앱 설치나 제거, 빌드, 링크 열기, 앱 데이터 다운로드는 먼저 사용자에게 묻습니다. [승인](approvals.md)을 참고하세요.
* **Activity**: 에이전트가 수행하는 모든 동작이 **Agent** 탭에 기록됩니다. [에이전트 활동](agent-activity.md)을 참고하세요.
* **Agent is driving**: 미러링 화면 하단의 상태와 사이드바의 기기 옆 ✨ 아이콘으로 에이전트가 기기를 사용 중인지 알 수 있습니다.
* **언제든 직접 조작**: 에이전트가 작업하는 중에도 사용자의 클릭과 키 입력은 항상 반영됩니다.