expo-mcp

Maestro가 통합된 Expo/React Native 앱 자동화를 위한 MCP 서버입니다.

주요 기능

세션 기반 아키텍처: start_session으로 Expo를 실행하고, 장치를 바인딩하며, 임대(lease)를 획득합니다. 수동으로 장치 ID를 관리할 필요가 없습니다.
TTL이 포함된 장치 임대: 2분 단위의 임대가 모든 장치 도구 호출 시 자동으로 갱신됩니다. 비활성 상태가 지속되면 만료되어 다른 인스턴스가 장치를 사용할 수 있게 합니다.
인스턴스 간 조정: 여러 MCP 인스턴스가 장치 충돌 없이 동시에 실행될 수 있습니다.
Expo 개발 서버 관리: Expo 개발 서버 시작/중지/재시작 기능을 제공합니다.
Maestro 통합: 전체 UI 자동화 도구(탭, 입력, 스크린샷 등)를 지원합니다.

설치

Claude Code 플러그인으로 설치 (권장)

두 개의 명령어를 실행한 후 재시작하세요:

# 1. Install the plugin. Just dismiss the "Expo App Directory" prompt
#    (or leave it empty) — the next step configures it for you.
/plugin marketplace add DaveDev42/expo-mcp
/plugin install expo-mcp --scope project

# 2. One-shot installer. Runs environment checks, auto-detects the Expo
#    app directory, and writes the userConfig directly into
#    .claude/settings.json. No /plugin UI round-trip needed.
/expo-mcp:install                     # auto-detect
/expo-mcp:install apps/mobile         # monorepo: pass the path explicitly

그런 다음 Claude Code를 재시작하면 모든 도구, 에이전트 및 기술을 사용할 준비가 완료됩니다.

설치 프로그램 플래그:

/expo-mcp:install apps/mobile --global        # write to ~/.claude/settings.json
/expo-mcp:install --scaffold-maestro          # also create a starter maestro/
/expo-mcp:install --skip-doctor               # skip prerequisite checks

설치 프로그램은 플러그인 디렉터리에서 번들된 Node 스크립트(doctor.mjs, detect-app-dir.mjs, scaffold-maestro.mjs)를 실행합니다. Claude Code는 처음 실행될 때 각각에 대해 승인을 요청할 것입니다. 계속하려면 승인해 주세요.

스크립트를 미리 승인(프롬프트 없음)하려면 프로젝트의 .claude/settings.local.json에 다음을 추가하세요. <PATH>는 각 스크립트가 처음 실행될 때 Claude Code가 표시하는 절대 경로로 대체하세요:

{
  "permissions": {
    "allow": [
      "Bash(node <PATH>/doctor.mjs:*)",
      "Bash(node <PATH>/detect-app-dir.mjs:*)",
      "Bash(node <PATH>/scaffold-maestro.mjs:*)"
    ]
  }
}

플러그인을 설치하면 자동으로 다음이 설정됩니다:

expo MCP 서버 (수동 .mcp.json 설정 불필요)
자동화된 모바일 앱 테스트를 위한 QA 에이전트 (qa)
Maestro YAML 테스트 흐름을 생성하기 위한 흐름 작성 에이전트 (flow-writer)
도구 참조 및 모범 사례가 포함된 사용 가이드 (/expo-guide)
실행 증거 없이 QA PASS 판정을 내릴 경우 경고하는 검증 훅

MCP 서버로만 설치

이 프로젝트는 GitHub를 통해서만 배포됩니다 (npm의 expo-mcp 이름은 다른 관련 없는 패키지이므로 사용하지 마세요). GitHub 참조를 통해 실행하세요:

npx -y github:DaveDev42/expo-mcp

Claude Code와 함께 사용하기

수동 MCP 설정

플러그인을 사용하지 않는 경우 .mcp.json에 다음을 추가하세요:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp"]
    }
  }
}

모노레포 설정

위치 인수를 사용하여 앱 디렉터리를 지정하세요:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile"]
    }
  }
}

특정 장치 사용

--device-id를 사용하여 특정 시뮬레이터나 에뮬레이터를 고정하세요:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--device-id=6D192F60-1234-5678-ABCD-000000000000"]
    }
  }
}

도구 필터링

--exclude-tools를 사용하여 특정 도구를 제외하세요:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile", "--exclude-tools=list_devices"]
    }
  }
}

또는 --tools를 사용하여 특정 도구만 노출하세요:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--tools=start_session,stop_session,take_screenshot"]
    }
  }
}

CLI 참조

Usage: expo-mcp [app-dir] [options]

Arguments:
  app-dir                      Path to Expo app directory (default: cwd)

Options:
  --device-id=<id>             Specific device to use (iOS simulator UUID or Android serial)
  --exclude-tools=tool1,tool2  Exclude specific tools from the MCP server
  --tools=tool1,tool2          Only expose specific tools
  -h, --help                   Show help message
  -v, --version                Show version number

빠른 시작

# 1. Start session (launches Expo + binds device + acquires lease)
start_session({ target: "ios-simulator" })

# 2. Use tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })
press_key({ key: "Enter" })
scroll({ direction: "down" })
swipe({ direction: "left" })

# 3. Run Maestro flows
run_maestro_flow({ flow_yaml: "- assertVisible: Welcome" })
check_maestro_flow_syntax({ flow_yaml: "- tap: Login" })

# 4. Reload app after code changes
reload_app()

# 5. Check logs if needed
get_logs({ level: "error" })

# 6. Stop session when done
stop_session()

플러그인 기능

Claude Code 플러그인으로 설치하면 다음과 같은 추가 기능을 얻을 수 있습니다:

QA 에이전트

모바일 QA 테스트를 qa 에이전트에 위임하세요. 시뮬레이터/에뮬레이터에서 엄격한 증거 요구 사항을 바탕으로 앱을 체계적으로 테스트합니다. 코드 리뷰만으로 판정하지 않습니다.

# In Claude Code, delegate to the QA agent:
"Test the login flow on iOS simulator"  →  delegates to qa agent

에이전트는 구조화된 방법론을 따릅니다: 앱 실행 → UI 검사 → 상호작용 → 검증 → PASS/FAIL/INCONCLUSIVE 판정 보고.

흐름 작성 에이전트

flow-writer 에이전트는 라이브 앱을 검사하고 Maestro YAML 테스트 흐름을 생성합니다:

# Ask the flow writer to create a test flow:
"Write a Maestro flow for the onboarding sequence"  →  delegates to flow-writer agent

구문을 검증하고, 흐름을 실행하여 작동 여부를 확인한 다음, .yaml 파일을 프로젝트에 작성합니다.

사용 가이드

/expo-guide를 통해 도구 참조 및 모범 사례에 액세스하세요:

/expo-guide                    # Full guide
/expo-guide session            # Session lifecycle
/expo-guide debugging          # Debugging tips

도구

수명 주기 도구

도구	설명
`get_session_status`	세션 상태 가져오기 (서버 상태, 장치 정보, 남은 임대 시간)
`start_session`	Expo 서버 시작, 장치 연결 및 장치 임대 획득
`stop_session`	Expo 서버 중지 및 모든 리소스 해제
`reload_app`	연결된 장치에서 앱 핫 리로드
`get_logs`	Metro 번들러 로그 가져오기 (레벨 및 소스별 필터링 가능)
`press_key`	키 누르기 (Enter, Backspace, Home, Lock, Tab, Volume Up/Down)
`scroll`	방향으로 화면 스크롤 (기본값: 아래)
`swipe`	방향 또는 정확한 시작/끝 좌표로 스와이프

start_session 옵션

옵션	유형	설명
`target`	`ios-simulator`	`android-emulator`	`web-browser`	실행할 대상 플랫폼
`device_id`	string	특정 장치 (iOS UUID 또는 Android 시리얼). 생략 시 자동 감지
`host`	`lan`	`tunnel`	`localhost`	연결 모드
`port`	number	서버 포트 (기본값: 8081, 사용 중일 경우 자동 증가)
`clear`	boolean	Metro 번들러 캐시 삭제
`dev`	boolean	개발 모드 (기본값: true)
`minify`	boolean	JavaScript 최소화
`max_workers`	number	최대 Metro 워커 수
`offline`	boolean	오프라인 모드
`scheme`	string	사용자 지정 URI 스킴
`simulator_name`	string	iOS 시뮬레이터 이름 (예: "iPhone 16 Pro")
`clean_state`	boolean	실행 전 시뮬레이터 상태 초기화 (기본값: false)
`auto_login`	object	앱 로드 후 Maestro 흐름 실행 (`{ flow_file: "path/to/flow.yaml" }`)

Maestro 도구

세션이 활성화되면 모든 Maestro 도구가 자동으로 작동합니다. device_id는 세션에서 주입됩니다:

도구	설명
`take_screenshot`	화면 캡처 (LLM 컨텍스트에 맞게 자동 크기 조정)
`tap_on`	텍스트, ID 또는 좌표로 UI 요소 탭
`input_text`	포커스된 필드에 텍스트 입력
`back`	뒤로 가기 버튼 누르기
`run_maestro_flow`	Maestro YAML 흐름 인라인 실행
`run_maestro_flow_files`	프로젝트 디렉터리에서 Maestro 흐름 파일 실행
`check_maestro_flow_syntax`	실행하지 않고 Maestro YAML 흐름 구문 검증
`inspect_view_hierarchy`	현재 화면의 UI 요소 트리 가져오기
`list_devices`	사용 가능한 모든 장치 나열 (활성 세션 없이 작동)

참고: 장치 도구는 활성 세션이 필요합니다. 먼저 start_session을 호출하세요. list_devices와 check_maestro_flow_syntax는 언제든지 호출할 수 있습니다.

장치 임대 시스템

장치 임대는 한 MCP 인스턴스가 장치를 무기한 점유하는 것을 방지합니다:

획득: start_session이 2분간의 장치 임대를 획득합니다.
자동 갱신: 모든 장치 도구 호출(take_screenshot, tap_on 등) 시 2분 타이머가 재설정됩니다.
만료: 2분 동안 장치 도구가 호출되지 않으면 임대가 만료되고 장치를 사용할 수 있게 됩니다.
재획득: start_session을 다시 호출하여 재획득합니다 (서버는 계속 실행되므로 재시작 불필요).
확인: get_session_status로 남은 임대 시간을 확인합니다.

여러 MCP 인스턴스는 파일 기반 레지스트리(/tmp/expo-mcp/instances/)를 통해 조정되므로 두 인스턴스가 동시에 같은 장치를 점유할 수 없습니다.

환경 변수

변수	설명	기본값
`EXPO_APP_DIR`	Expo 앱 디렉터리 경로 (CLI 위치 인수가 우선)	현재 작업 디렉터리
`MAESTRO_CLI_PATH`	Maestro CLI 경로	`~/.maestro/bin/maestro`
`ESSENTIAL_TOOLS`	노출할 도구의 쉼표 구분 목록 (`--tools`가 우선)	모든 도구
`EXCLUDE_TOOLS`	제외할 도구의 쉼표 구분 목록 (`--exclude-tools`가 우선)	없음
`LOG_BUFFER_SIZE`	메모리에 유지할 최대 로그 라인 수	400
`EXPO_TOKEN`	Expo 인증 토큰 (오프라인 모드가 비활성화된 경우에만 필요)	없음

작동 원리

세션 시작: start_session이 Expo 개발 서버를 시작하고, 장치 연결을 기다린 후 임대를 획득합니다.
장치 바인딩: 연결된 장치 ID가 2분 TTL과 함께 세션에 저장됩니다.
자동 주입: 모든 Maestro 장치 도구가 세션의 장치 ID를 자동으로 사용합니다.
임대 갱신: 모든 장치 도구 호출 시 임대 타이머가 재설정됩니다.
세션 종료: stop_session이 모든 것을 정리하거나, 비활성 상태가 지속되면 임대가 만료됩니다.

비대화형 환경 (CI/CD, AI 에이전트)

이 MCP 서버는 CI 환경(CI=1)에서 실행될 때 자동으로 --offline 모드를 활성화합니다. 이를 통해 EXPO_TOKEN 없이도 앱이 작동할 수 있습니다.

오프라인 모드의 기능

Expo 서버 통신(매니페스트 서명)을 건너뜁니다.
앱의 네트워크 기능(API 호출, fetch 등)에는 영향을 주지 않습니다.
터널 모드(--tunnel)는 오프라인 모드에서 사용할 수 없습니다.

Expo 계정 기능이 필요한 경우

Expo 인증이 필요한 기능을 사용하려면 오프라인 모드를 비활성화하고 EXPO_TOKEN을 제공하세요:

{
  "mcpServers": {
    "expo": {
      "env": {
        "EXPO_TOKEN": "your-token-here"
      }
    }
  }
}

그런 다음 offline: false로 start_session을 호출하세요:

start_session({ target: "ios-simulator", offline: false })

요구 사항

Node.js >= 18
Xcode (iOS 시뮬레이터용)
Android Studio (Android 에뮬레이터용)
Maestro CLI (UI 자동화용)

라이선스

MIT

Expo MCP Server