appletv-mcp

Apple TV をローカルネットワーク経由で AI エージェントに完全制御させる 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 が 2 回表示されます）:

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、issue #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