appletv-mcp

로컬 네트워크를 통해 AI 에이전트가 Apple TV를 완전히 제어할 수 있게 해주는 MCP 서버입니다. 리모컨도 Siri도 필요 없습니다.

pyatv(Companion + AirPlay 프로토콜) 기반으로 구축되었습니다. 자매 프로젝트인 appletv-remote는 서버 대신 Claude Code / opencode 스킬 형태로 동일한 기능을 제공합니다.

할 수 있는 작업

제어 도구는 선택적 device 이름을 받아 기본이 아닌 TV를 대상으로 지정할 수 있습니다(atv_scan, atv_devices, atv_use는 예외 — 이들은 페어링 구성 자체에 적용됩니다).

설정

사전 요구 사항: uv (brew install uv).

1. TV당 한 번 페어링 (대화형; TV에 4자리 PIN이 두 번 표시됩니다):

uv run python scripts/pair.py

자격 증명은 소유자만 읽을 수 있는 ~/.config/appletv-remote/devices.json에 저장됩니다(appletv-remote 스킬과 공유). 이 파일을 비공개로 유지하세요 — TV에 대한 완전한 제어 권한을 부여합니다.

비대화형(에이전트 주도) 방식: ATV_PIN_FILE=/tmp/atv_pin.txt를 설정하고 pair.py <name-filter>를 실행한 후 각 PIN을 해당 파일에 작성합니다.

2. 서버를 MCP 클라이언트에 등록합니다. opencode의 예시(~/.config/opencode/opencode.json):

"mcp": {
  "appletv": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/path/to/appletv-mcp", "python", "server.py"],
    "enabled": true
  }
}

Claude Code의 경우: claude mcp add appletv -- uv run --directory /path/to/appletv-mcp python server.py

참고 사항 및 주의사항

• pyatv는 병합되지 않은 포크의 정확한 커밋에 고정되어 있습니다. tvOS 26에서 play_url을 수정하는 버전입니다 (PR #2846, 이슈 #2821/#2774). 병합 및 릴리스되면 기본 pyatv로 되돌리세요.

• Netflix 딥 링크는 2025년 9월 tvOS 앱 업데이트 이후로 신뢰할 수 없습니다. atv_watch는 정상적으로 대체 동작하며, 언제든지 atv_launch_app("netflix") + atv_type(...)을 사용할 수 있습니다.

• JustWatch 조회는 기본적으로 미국/영어로 설정됩니다. ATV_JW_COUNTRY / ATV_JW_LANGUAGE로 재정의하세요.

• YouTube 스트림은 AirPlay 2를 통해 HLS로 푸시됩니다: 재생은 TV에 대기열로 추가되며 도구가 반환된 후에도 계속됩니다. URL은 약 6시간 후 만료됩니다.

• 연결 시 FetchAttentionState failed 경고는 무해합니다(포크 특성). 명령은 정상 작동합니다.

• tvOS 26(Apple TV 4K 3세대)에서 테스트되었습니다. tvOS 13+에서 작동해야 합니다.

라이선스

MIT