Apple TV MCP について
Apple TV MCPは、MCP対応エージェントからApple TVをローカル操作し、画面を確認するサーバーです。意味に沿った操作と、結果確認に使える任意のオンデマンドスクリーンショットを提供します。
主な機能
- 01アプリとディープリンクを開く
- 02tvOS画面を操作する
- 03再生、音量、電源を制御する
- 04フォーカス中の入力欄に文字を入力する
- 05デバイスと再生状態を取得する
- 06任意のスクリーンショットを撮る
活用シーン
- 01アプリ内でコンテンツを検索する
- 02再生中に一時停止やシークを行う
- 03画面操作後の状態を確認する
- 04デバイスと再生状態を確認する
MCP 対応
ローカルのstdio経由で、Apple TVの操作と状態取得をMCPツールとして提供します。任意のスクリーンショットツールは、撮影時点の画像をネイティブなMCP画像コンテンツとして返します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
14掲載時のツール一覧 · 2 週間前に更新
このツールにパラメーターはありません。
詳細
Apple TV MCP：AI エージェントが Apple TV を操作し、画面を確認できるローカル MCP サーバー
アプリを開き、tvOS を操作し、再生を制御し、検索語を入力し、音量を調整し、電源を管理し、スクリーンショットを撮影することで、マルチモーダルエージェントが実際に何が起きたのかを確認できます。
You:
Open YouTube and search for OpenAI.
Agent:
→ opens YouTube
→ takes a screenshot
→ sees the current interface
→ navigates to Search
→ types "OpenAI"
→ takes another screenshot
→ verifies the results
Apple TV MCP は、MCP 対応 AI エージェントがローカルで操作し、画面を確認できるデバイスへと Apple TV を変えます。
ホスト型バックエンドは不要です。カスタム Apple TV アプリも不要です。クラウドアカウントも不要です。
Apple TV MCP を選ぶ理由
従来の Apple TV 自動化の多くは、画面を確認できません。
スクリプトで「右」や「選択」を押すことはできますが、その後画面に何が表示されたかは、通常わかりません。
Apple TV MCP は、セマンティックな操作とその時点での視覚的な観察を組み合わせます。
| 従来の Apple TV 自動化 | Apple TV MCP |
|---|---|
| 画面を確認せずリモートコマンドを送信する | 操作の合間にスクリーンショットを撮影する |
| アプリごとにスクリプトを作成する | 任意の tvOS インターフェースを操作する |
| 操作が成功したか推測する | 画面を確認して検証する |
| AI システムごとにカスタム統合が必要 | 標準の MCP ツールインターフェース |
| リモートコマンドのみ | アプリ、再生、テキスト、電源、音量、ナビゲーション、画面確認 |
その結果、AI エージェントが実際に活用できるフィードバックループが実現します。
screenshot
↓
model sees tvOS
↓
chooses an action
↓
press / type / open
↓
screenshot again
↓
verify
可能な場合は、引き続きセマンティックツールを優先してください。スクリーンショットが役立つのは、直接 API を公開していないインターフェースを操作する必要がある場合です。
数秒でインストール
Apple TV MCP には Python 3.14 が必要です。
推奨
uv tool install appletv-mcp
または：
pipx install appletv-mcp
次に、Apple TV をペアリングします。
atvremote wizard
Apple TV MCP を設定します。
appletv-mcp configure
セットアップを確認します。
appletv-mcp doctor
そして MCP サーバーを起動します。
appletv-mcp serve
ソースからインストール
git clone https://github.com/trevor-nichols/appletv-mcp.git
cd appletv-mcp
uv sync --locked
uv run appletv-mcp configure
uv run appletv-mcp doctor
uv run appletv-mcp serve
何ができますか？
Apple TV MCP は、エージェントが実際に達成したい作業に合わせて分類された 14 個のツールを提供します。
確認
- 現在の Apple TV 画面のスクリーンショットを撮影する
- デバイス、接続、再生、メディアの状態を読み取る
- Apple TV で利用できる機能を確認する
アプリ
- インストール済みアプリを一覧表示する
- 名前でアプリを開く
- バンドル識別子でアプリを開く
- ディープリンクやカスタムアプリ URL を開く
ナビゲーション
- 上
- 下
- 左
- 右
- 選択
- 戻る
- ホーム
- メニュー
- その他の対応済みリモート操作
リモートナビゲーションは、意図的に非冪等な操作として扱われます。接続障害が発生し、状態が不確かな場合でも、Apple TV MCP はナビゲーションコマンドをむやみに再送しません。
再生
- 再生
- 一時停止
- 再生／一時停止を切り替える
- 停止
- 次へ
- 前へ
- 絶対位置へシークする
- 前方または後方へスキップする
テキスト
フォーカスされている tvOS のテキストフィールドに直接入力します。
次のような用途に便利です。
- 検索
- ユーザー名
- アプリの操作
- クエリの入力
音量
- 音量が取得可能な場合に読み取る
- 音量を指定したレベルに設定する
- 音量を相対的に調整する
電源
- Apple TV の電源を入れる
- Apple TV の電源を切る
電源操作には異なる再試行のセマンティクスが適用されるため、電源オフコマンドが成功した直後に、再接続の試行によってデバイスの電源が誤って入ることはありません。
エージェントに目を与える
オプションのスクリーンショットバックエンドがあることで、Apple TV MCP は単なるリモコンにとどまりません。
MCP ツールは次のように動作します。
apple_tv_screenshot
現在の Apple TV 画面を、ネイティブの MCP 画像コンテンツとして返します。
つまり、マルチモーダル MCP クライアントはツールを呼び出し、返された画像を直接確認できます。
たとえば：
Agent:
apple_tv_screenshot()
→ sees the Apple TV Home Screen
→ sees YouTube highlighted
apple_tv_press(button="select")
apple_tv_screenshot()
→ sees the YouTube interface
モデルがローカルの screen.png パスにアクセスする必要はなく、テキスト応答に base64 が含まれることもありません。
PNG 画像そのものが MCP 経由で返されます。
スクリーンショットは撮影時点の状態です
Apple TV MCP は、画面を継続的に監視するわけではありません。
スクリーンショットが示すのは、撮影した時点で画面に表示されていた内容です。
その後にエージェントが別の操作を行うと、前のスクリーンショットはすでに古くなっている可能性があります。
想定される使い方は次のとおりです。
observe
→ act
→ observe
→ verify
スクリーンショットを有効にする
スクリーンショットのサポートは任意です。
スクリーンショットを有効にしなくても、Apple TV の操作は通常どおり行えます。
専用のヘルパーをインストールします。
uv tool install appletv-screenshot
スクリーンショットシステムでは、pyatv のペアリングとは別の Apple 開発者用／RemoteXPC ペアリングを使用します。
開発者アクセス用にペアリングします。
pymobiledevice3 remote pair
次に、1 台の Apple TV 用にスクリーンショットヘルパーを設定します。
appletv-screenshot configure --udid <UDID>
すべてをまとめて確認します。
appletv-mcp doctor
正常にインストールされていれば、Apple TV の操作と画面キャプチャの両方が利用可能であることが表示されます。
スクリーンショットヘルパーには、独自の設定、依存関係、ライフサイクルがあります。pymobiledevice3 はメインの appletv-mcp パッケージからインポートされません。
スクリーンショットの詳しい設定方法やトランスポートのトラブルシューティングについては、次を参照してください。
sidecars/appletv-screenshot/README.md
クイックスタート
一連の手順は次のとおりです。
# Install
uv tool install appletv-mcp
# Pair for Apple TV control
atvremote wizard
# Choose the Apple TV
appletv-mcp configure
# Optional: install visual observation
uv tool install appletv-screenshot
# Optional: developer pairing for screenshots
pymobiledevice3 remote pair
appletv-screenshot configure --udid <UDID>
# Verify
appletv-mcp doctor
# Run the MCP server
appletv-mcp serve
MCP クライアントを接続する
Apple TV MCP はローカルの stdio MCP トランスポートを使用します。
ローカルの stdio サーバーを起動できる MCP クライアントであれば、どれでも使用できます。
一般的な設定は次のようになります。
{
"mcpServers": {
"appletv-mcp": {
"command": "appletv-mcp",
"args": ["serve"]
}
}
}
Apple TV MCP をクローンしたリポジトリから実行する場合は、次のようになります。
{
"mcpServers": {
"appletv-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/appletv-mcp",
"run",
"appletv-mcp",
"serve"
]
}
}
}
このサーバーは HTTP エンドポイントを公開せず、OAuth も必要ありません。
ツール
| ツール | 目的 |
|---|---|
apple_tv_status | デバイスと再生の状態を構造化データで読み取る |
apple_tv_capabilities | 正規化された機能の利用可否を確認する |
apple_tv_list_apps | 起動可能なアプリケーションを一覧表示する |
apple_tv_power | Apple TV の電源をオンまたはオフにする |
apple_tv_open_app | アプリケーションを開く |
apple_tv_open_url | URL またはディープリンクを開く |
apple_tv_press | Apple TV のリモコンボタンを押す |
apple_tv_playback | 再生を操作する |
apple_tv_seek | 再生位置を指定した位置に移動する |
apple_tv_skip | 前後にスキップする |
apple_tv_set_text | フォーカス中のキーボードテキストを置き換える |
apple_tv_set_volume | 音量を指定した値に設定する |
apple_tv_adjust_volume | 音量を相対的に調整する |
apple_tv_screenshot | 1 枚のスクリーンショットを MCP 画像コンテンツとして返す |
画像コンテンツを返すのは、構造化された結果ではなく、スクリーンショットツールだけです。
仕組み
Apple TV MCP では、操作と視覚的な確認を意図的に分離しています。
AI Agent
│
▼
Apple TV MCP
/ \
/ \
▼ ▼
semantic control screen capture
│ │
pyatv appletv-screenshot
│ │
│ pymobiledevice3
│ │
│ RemoteXPC / DVT
│ │
└──── Apple TV ─┘
操作
Apple TV の操作には pyatv を使用します。
Apple TV MCP はその上に、次の機能を持つセマンティックなアプリケーションレイヤーを追加します。
- アプリを確実に解決する
- 機能の利用可否を確認する
- 接続のライフサイクルを管理する
- 安全に再試行する
- 冪等でないコマンドを保護する
- MCP の結果を正規化する
Apple TV の安定した識別子が、正確な識別情報として使用されます。
最後に確認された IP アドレスは、あくまで最適化のために使用されます。Apple TV のアドレスが変わった場合、Apple TV MCP は識別子を使って再検出し、優先ホストを更新できます。
ビジョン
スクリーンショットには、別途用意された appletv-screenshot ヘルパーを使用します。
このヘルパーは pymobiledevice3 を使用して RemoteXPC 経由で Apple の開発者向けサービスに接続し、DVT を通じてスクリーンショットを要求します。
デフォルトのトランスポート戦略は次のとおりです。
macOS:
native → userspace → tunneld
Linux / Windows:
userspace → tunneld
通常の Wi-Fi ユーザー空間経路では、root 権限も、常時稼働するトンネルデーモンも必要ありません。
このヘルパーは別プロセスとして動作するため、プロトコルスタック、依存関係、ペアリング記録、障害の影響範囲が Apple TV の制御から分離されます。
pymobiledevice3 は、別途配布される appletv-screenshot ヘルパー内に限定されています。メインの appletv-mcp パッケージはこれをインポートもバンドルもしません。2 つのプロセスは、限定的なコマンドライン／ファイルのインターフェースを介して通信します。
エージェント向けの設計
MCP インターフェースでは、意図的に生の Apple プロトコルではなく、意味に基づいた操作を公開しています。
エージェントは次のように考える必要があります。
open YouTube
pause playback
seek to 2:00
type "Severance"
set volume to 35%
take a screenshot
次のように考えるのではありません。
send Companion command
call MRP endpoint
construct RemoteXPC request
意味に基づいた操作がある場合は、それを使用してください。
視覚的なナビゲーションは、それが必要なインターフェースでの代替手段です。
プライバシーとセキュリティ
Apple TV MCP はローカルで動作するように設計されています。
- ホスト型の Apple TV MCP バックエンドはありません
- クラウドアカウントは不要です
- MCP はローカルの stdio トランスポートを使用します
- Apple TV のペアリング認証情報はユーザーのマシン上に保持されます
- RemoteXPC のペアリング記録はスクリーンショットヘルパー内に保持されます
- 認証情報が MCP のパラメーターになることはありません
- 認証情報がモデルに返されることはありません
- キーボード入力のテキストは通常のログに出力されません
- スクリーンショットは明示的に要求された場合にのみ撮影されます
- スクリーンショットのバイトデータはログに記録されません
- 撮影中、スクリーンショットはプライベートな一時ディレクトリにのみ保存されます
- MCP の結果が作成された後、一時スクリーンショットファイルは削除されます
- コマンドの実行後にスクリーンショットが自動撮影されることはありません
- ヘルパーはシェルを介さずに起動されます
- DRM の回避は試みません
デバッグモードでも、低レベルの Companion トラフィックには機密性の高いキーボード入力やペアリングデータが含まれる可能性があるため、生の pyatv プロトコルログは無効のままです。
保護された動画
ストリーミングアプリケーションでは、DRM を使用して動画を保護する場合があります。
その場合、スクリーンショットには次のように表示されることがあります。
black video
blank video
redacted video
一方で、メニューや再生コントロールは表示されたままです。
これは想定どおりの動作です。
Apple TV MCP は、保護された動画の黒い領域を次の証拠として解釈しません。
- 再生に失敗した
- Apple TV の電源が切れた
- スクリーンショットの撮影に失敗した
また、DRM を回避しようとすることもありません。
制限事項
Apple TV MCP の初期スコープは意図的に限定されています。
Apple TV は 1 台
各サーバー設定で制御できる Apple TV は 1 台です。
複数デバイスへのルーティングは、現在、公開 MCP インターフェースの対象外です。
スクリーンショットは動画ではありません
apple_tv_screenshot は一度に 1 フレームを撮影します。
次の機能はありません。
- 連続ストリーム
- バックグラウンドでの画面監視
- 画面録画
- スクリーンショットの自動ループ
フォーカスは意味的ではなく視覚的に判断します
pyatv は、現在フォーカスされている tvOS 要素を示す汎用的なシグナルを提供しません。
エージェントは、適切な場合にスクリーンショットからフォーカスを推測できます。
media_app は foreground_app ではありません
Apple TV のステータスから、現在のメディアメタデータに関連付けられたアプリケーションを特定できる場合があります。
それだけでは、どのアプリケーションが画面上で前面に表示されているかを確実に特定できません。
Apple の開発者向けサービスは変更されることがあります
スクリーンショット機能は、pymobiledevice3 を通じて公開される Apple の開発者向けプロトコルに依存しています。
tvOS の変更に伴い、今後互換性の更新が必要になる場合があります。
スクリーンショット機能はオプションです
スクリーンショット以外の Apple TV MCP ツールはすべて、スクリーンショットヘルパーがインストールされていなくても動作します。
設定
Apple TV MCP は、プラットフォーム標準の設定ディレクトリにアプリケーション設定を保存します。
一般的な設定項目は次のとおりです。
{
"device_identifier": "...",
"device_name": "Living Room",
"preferred_host": "192.168.1.10",
"scan_timeout_seconds": 5.0,
"command_timeout_seconds": 15.0,
"screen_capture": {
"command": "appletv-screenshot",
"timeout_seconds": 20.0,
"max_image_bytes": 33554432
}
}
ペアリング認証情報はこのファイルには保存されません。
MCP ホストが最小限の PATH でプロセスを起動する場合は、screen_capture.command にスクリーンショットヘルパーの絶対パスを設定してください。
Apple TV MCP v0.1 の既存の設定ファイルも引き続き使用できます。
Doctor
次を実行します：
appletv-mcp doctor
インストール全体を診断します。
以下のような項目を確認します：
configuration
pyatv storage
Apple TV discovery
stable device identity
connection
capabilities
screenshot helper
screenshot helper contract
screen-capture target
real screenshot capture
スクリーンショットのサポートは任意です。
ヘルパーがインストールされていない場合、Doctor は Apple TV の制御に問題があるとは判断せず、スキップされたものとして報告します。
トラブルシューティング
Apple TV が見つからない
次の点を確認してください：
- Apple TV の電源が入っている
- コンピューターと Apple TV が同じローカルネットワークに接続されている
atvremote wizardが正常に完了している
その後、次を再実行してください：
appletv-mcp configure
appletv-mcp doctor
Apple TV の IP アドレスが変わった
これは想定どおりです。
Apple TV MCP は古い IP アドレスを信頼するのではなく、安定した識別子を使って設定済みデバイスを識別します。
アプリが開かない
次を使用して、デバイスが現在公開しているアプリケーションを確認してください：
apple_tv_list_apps
アプリケーション名の照合は、曖昧な一致ではなく決定論的に行われます。
テキスト入力に失敗する
Apple TV でテキストフィールドにフォーカスが当たっている必要があります。
スクリーンショットのヘルパーが見つからない
次をインストールしてください：
uv tool install appletv-screenshot
または、Apple TV MCP に絶対パスを設定してください。
スクリーンショットの対象が設定されていない
次を実行してください：
appletv-screenshot configure --udid <UDID>
スクリーンショットのペアリングに失敗する
開発者向けスクリーンショットのペアリングは atvremote とは別のものです。
次を実行してください：
pymobiledevice3 remote pair
スクリーンショットが黒い
保護されたコンテンツでは、意図的にビデオフレームが非表示になる場合があります。
tvOS のメニューまたはアプリケーションのインターフェースを開いて、もう一度キャプチャしてみてください。
開発
リポジトリをクローンします：
git clone https://github.com/trevor-nichols/appletv-mcp.git
cd appletv-mcp
インストールします：
uv sync --locked
ルートの品質チェック一式を実行します：
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build
スクリーンショットのヘルパーは独立した Python プロジェクトです：
cd sidecars/appletv-screenshot
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
ルートパッケージは、意図的に pymobiledevice3 に依存せず、同梱もしていません。
ライブテスト
通常のテストではフェイクを使用するため、Apple のハードウェアは必要ありません。
読み取り専用の Apple TV 統合テストは、明示的にオプトインした場合にのみ実行されます：
APPLE_TV_INTEGRATION_TESTS=1 uv run pytest -m live
Apple TV の状態を変更する可能性のあるテストには、追加のオプトインが必要です：
APPLE_TV_INTEGRATION_TESTS=1 \
APPLE_TV_LIVE_WRITES=1 \
uv run pytest -m live
操作する意図のないデバイスに対して、ライブ書き込みテストを決して有効にしないでください。
貢献
貢献を歓迎します。
プルリクエストを作成する前に：
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build
変更がスクリーンショットのヘルパーに影響する場合は、独立した品質チェックも実行してください。
プロジェクトの中核となるアーキテクチャを維持してください：
control = pyatv
observation = external screenshot helper
MCP = semantic interface presented to the agent
明確な意味上の理由がない限り、MCP コントラクトを通じて Apple のプロトコルの詳細をそのまま公開しないでください。
ライセンス
このリポジトリには、個別に配布されるコンポーネントが 2 つ含まれています。
Apple TV MCP
appletv-mcp は MIT ライセンスの下でライセンスされています。
pymobiledevice3 をインポート、同梱、または配布することはありません。
Apple TV Screenshot
sidecars/appletv-screenshot/ 配下の任意のヘルパー appletv-screenshot は、GPL-3.0-or-later の下でライセンスされています。
このヘルパーが直接使用する pymobiledevice3 も、GPL-3.0-or-later の下でライセンスされています。
2 つのコンポーネントは、1 回限りのサブプロセスインターフェースを通じて通信します。
リポジトリ全体の対応関係については、LICENSING.md を参照してください。
シンプルなアイデアを実現するために
AI エージェントは、自らのアクションの効果を確認できると、はるかに便利になります。
Apple TV MCP は、そのループの両方を提供します：
control the Apple TV
+
see the Apple TV
これにより、エージェントは盲目的にボタンを押すのではなく、tvOS を操作して結果を確認し、次に何をするか判断できます。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。