appletv-mcp

Сервер MCP, который даёт ИИ-агенту полный контроль над Apple TV в локальной сети — без пульта, без Siri.

Построен на pyatv (протоколы Companion + AirPlay). Родственный проект appletv-remote предоставляет те же возможности в виде навыка для Claude Code / opencode, а не сервера.

Что он умеет

Инструменты управления принимают необязательное имя device для выбора нестандартного ТВ (исключения — atv_scan, atv_devices и atv_use; они применяются к самой конфигурации сопряжения).

Настройка

Предварительное требование: uv (brew install uv).

1. Сопряжение один раз для каждого ТВ (интерактивно; ТВ показывает 4-значный PIN-код дважды):

uv run python scripts/pair.py

Учётные данные хранятся только для владельца в ~/.config/appletv-remote/devices.json (общие с навыком appletv-remote). Держите этот файл в тайне — он даёт полный контроль над ТВ.

Неинтерактивный режим (управляемый агентом): установите 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 привязан к точному коммиту необъединённого форка, исправляющему play_url на tvOS 26 (PR #2846, issues #2821/#2774). После объединения и релиза вернитесь к стандартному pyatv.

• Глубокие ссылки Netflix ненадёжны после обновления приложения tvOS в сентябре 2025; atv_watch корректно откатывается, и вы всегда можете atv_launch_app("netflix") + atv_type(...).

• Поиск JustWatch по умолчанию использует US/en; переопределите с помощью ATV_JW_COUNTRY / ATV_JW_LANGUAGE.

• Потоки YouTube передаются как HLS через AirPlay 2: воспроизведение ставится в очередь на ТВ и продолжается после возврата инструмента. URL-адреса истекают через ~6 часов.

• Предупреждение FetchAttentionState failed при подключении безвредно (особенность форка); команды продолжают работать.

• Протестировано на tvOS 26 (Apple TV 4K gen 3). tvOS 13+ должно работать.

Лицензия

MIT