appium‑mcp – AI 강화 Appium 서버 (모바일 테스트 자동화용)

무엇인가요 – 표준 Appium 자동화 프레임워크 위에 위치하는 Node.js 기반의 MCP(Model Context Protocol) 서버입니다. 일반적인 Appium 기능(안드로이드 UiAutomator2, iOS XCUITest 등)을 제공할 뿐 아니라, AI 기반 보조 기능도 추가하여 자연어로 디바이스를 제어하고, 로케이터를 자동 생성하며, 일반 영어 문장에서 Java/TestNG 테스트 코드를 생성할 수 있습니다.

핵심 기능 (README에 기술됨)

카테고리	제공되는 기능
크로스 플랫폼 모바일 자동화	내장된 Appium 드라이버를 사용하여 안드로이드 및 iOS 디바이스(실기기, 에뮬레이터, 시뮬레이터)를 지원합니다.
AI 기반 요소 찾기	스크린샷을 설정 가능한 비전 모델(OpenAI 호환)에 전송하고 자연어 쿼리에 부합하는 UI 요소를 반환하는 도구(`appium_ai`)를 제공합니다.
지능형 로케이터 생성	우선순위 규칙에 따라 견고한 선택자(XPath, 접근성 ID 등)를 생성하여 테스트의 불안정성 감소를 도와줍니다.
자동 테스트 생성	자연어 테스트 설명을 Java/TestNG 코드로 변환하며, Page Object Model을 사용합니다.
세션 관리	간단한 MCP 명령어로 Appium 세션을 생성, 연결, 정리할 수 있으며, 내장된 로컬 드라이버와 원격 WebDriver/Appium 서버를 모두 지원합니다.
다국어 지원	AI 레이어는 영어, 스페인어, 중국어, 일본어, 한국어 등 여러 언어를 이해할 수 있습니다.
관측성(Observability)	선택적 OpenTelemetry 트레이싱, 각 작업에 대한 구조화된 "증거" 기록, 그리고 설정 가능한 스크린샷 저장 기능을 제공합니다.
확장 가능한 플러그인 API	개발자가 커스텀 도구를 추가하거나 기존 도구를 교체할 수 있도록 허용합니다.

일반적인 워크플로우

설치 – 서버를 (npx appium-mcp@latest) 설치하고 IDE의 MCP 설정(Cursor, Gemini CLI, Claude Code 등)에 추가합니다.
환경 변수 설정 – 최소한 ANDROID_HOME (macOS에서는 iOS 도구)를 설정하고, 필요 시 CAPABILITIES_CONFIG를 장치를 설명하는 JSON 파일 경로로 지정합니다.
세션 시작 – 서버가 로컬 드라이버를 시작(action=create)하거나 기존 원격 Appium 서버에 연결(remoteServerUrl)할 수 있습니다.
AI에 요청 – "Login 버튼을 탭하세요" 또는 "라벨이 Email인 필드를 찾아주세요"와 같은 자연어 요청을 보냅니다. 서버는 AI_VISION_* 변수로 설정된 비전 모델을 사용해 요소를 찾고, 해당 작업을 수행합니다.
코드 생성 – "로그인 후 웰컴 화면에 사용자 이름이 표시되는지 확인하세요"와 같은 설명을 주면, Page Object 템플릿을 포함한 실행 가능한 Java/TestNG 코드를 받습니다.
옵션 트레이싱 – APPIUM_MCP_OTEL_ENABLED=true로 OpenTelemetry를 활성화하면 각 도구 호출에 대한 스팬을 수집할 수 있어 CI 디버깅에 유용합니다.

설치 및 빠른 시작 (README에서)

{
  "mcpServers": {
    "appium-mcp": {
      "disabled": false,
      "timeout": 100,
      "type": "stdio",
      "command": "npx",
      "args": ["appium-mcp@latest"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk",
        "CAPABILITIES_CONFIG": "/path/to/your/capabilities.json"
      }
    }
  }
}

Cursor IDE에서는 한 번의 클릭 설치 배지로 서버를 자동으로 추가할 수 있습니다.
Gemini CLI 사용 시: gemini mcp add appium-mcp npx -y appium-mcp@latest.
Claude Code CLI 사용 시: claude mcp add appium-mcp -- npx -y appium-mcp@latest.

설정 요약

AI 비전 – AI_VISION_ENABLED=true로 활성화하고 AI_VISION_API_BASE_URL와 AI_VISION_API_KEY를 제공하세요. 기본 모델은 Qwen3-VL-235B-A22B-Instruct입니다.
문서 도구 – APPIUM_MCP_DOCS_ENABLED=true로 옵션 활성화. 선택적 @appium/mcp-documentation 패키지 필요.
OpenTelemetry – APPIUM_MCP_OTEL_ENABLED로 전환 가능. OTEL_* 변수를 사용해 에크스포터 엔드포인트, 서비스 이름 등을 설정할 수 있습니다.
세션 정리 – APPIUM_MCP_ON_CLIENT_DISCONNECT로 제어(delete_all 또는 skip).
증거 기록 – APPIUM_MCP_EVIDENCE=true로 설정하면 각 요소 찾기 또는 제스처 응답에 구조화된 JSON 블록을 첨부하여 CI 진단에 도움이 됩니다.

누구에게 적합한가요?

수동으로 선택자를 작성하는 대신 어시스턴트와 대화하여 모바일 테스트를 더 빠르게 작성하고 싶은 QA 엔지니어.
신뢰할 수 있는 AI 보조 요소 위치 및 자동 테스트 틀 생성이 필요한 CI 파이프라인을 구축하는 개발자.
LLM 기반 개발 도구(Cursor, Claude, Gemini)를 채택하고 있으며, 이러한 IDE와 통합 가능한 즉시 사용 가능한 MCP 서버를 찾는 팀.
모바일 디바이스에서 비전 기반 UI 상호작용을 연구하는 연구자. 서버는 어떤 OpenAI 호환 비전 엔드포인트에도 연결 가능합니다.

제한 사항 및 요구 사항 (README 기준)

Node 22+, Java 8+, Android SDK(안드로이드용), Xcode(iOS용, macOS 전용) 필요.
AI 비전 기능은 필요한 API 엔드포인트와 키가 제공된 경우에만 작동합니다. 그렇지 않으면 appium_ai 도구는 등록되지 않습니다.
서버 프로세스당 하나의 활성 Appium 세션만 유지됩니다. 병렬 세션은 별도의 서버 인스턴스가 필요합니다.
"일반" 플랫폼 모드는 원격 Appium 서버에 임의의 능력 세트를 전달할 수 있지만, 로컬 내장 드라이버는 안드로이드와 iOS에 한정됩니다.

결론

appium-mcp는 잘 알려진 Appium 자동화 스택에 자연어 기반 요소 위치, 자동 생성 테스트 코드, 다국어 지원 등의 AI 기능을 추가하고, MCP 프로토콜을 통해 현대적인 LLM 중심 IDE와 원활하게 통합되는 진정한 소프트웨어 프로젝트입니다. 단순한 튜토리얼이나 링크 모음이 아니라, AI 강화 모바일 테스트 분야에 확고한 위치를 차지하고 있습니다.

appium/appium-mcp