Roon Desktop MCP

Roon Desktop MCP 把 Roon 桌面操作接進 AI 助手的工作流程。你可以用自然語言交代任務，讓支援 MCP 的助手讀取畫面、找到目標，協助搜尋、整理歌單或檢視設定，再重新讀回結果。

它補上既有 Roon API 工具之外的桌面操作，透過本機 stdio 連接受信任的 MCP host。預設只開放觀察；要送出桌面輸入，需由本機操作者明確啟用。

可以怎麼用

情境示意圖；介面為概念插畫，實際操作以當前 Roon 畫面為準。

這些任務由 agent 依照畫面逐步操作。35 條流程目前都是 guided_unverified / agent_assisted，提供前提、操作與驗證指引；每次實際寫入仍需確認授權與結果。查看全部流程 →

Related MCP server: PC Controller MCP Server

每一步都有畫面與結果可查

flowchart LR
    A["① 觀察<br/>取得新畫面"] --> B["② 定位<br/>確認唯一目標"]
    B --> C["③ 操作<br/>只送出一次動作"]
    C --> D["④ 讀回<br/>確認實際結果"]
    classDef step fill:#f0ebfa,stroke:#8a76b4,color:#292334;
    classDef result fill:#eef5f0,stroke:#719982,color:#24382b;
    class A,B,C step;
    class D result;

結果不明時，重新觀察與核對，不重播輸入；確認後再記錄結果。

1. 觀察： desktop_observe 取得截圖、可用的 UIA、Windows OCR 與視窗身分。

2. 定位： desktop_find 或 agent 在仍有效的 frame 中確認目標。

3. 操作： desktop_act / desktop_navigate 執行單一動作，以 operation_id 記錄狀態。

4. 讀回： 重新觀察，必要時搭配完整 manifest 或既有 Roon API 讀回；desktop_reconcile 記錄呼叫端提供的結果證據，不自行做語意驗證。

Roon 主畫面多為 canvas，UIA 與 OCR 不一定能取得完整內容。因此工具會檢查 frame 與視窗身分，避免沿用失效位置；一次點擊送達，還需要結果讀回才能判斷工作是否完成。

歌單、Queue 或 DSP 的保存結果，需要完整清單、設定值或既有 Roon API 的讀回；單靠畫面變化或 OCR 無法證明已保存。

目前驗證到哪裡

測試歌單的驗收順序

flowchart LR
    A[建立] --> B[加入曲目] --> C[重新排序] --> D[改名] --> E[移除曲目] --> F[刪除測試歌單]
    classDef verified fill:#eef5f0,stroke:#719982,color:#24382b;
    class A,B,C,D,E,F verified;

上述驗收限於該測試情境。既有歌單、完整 Queue，以及 audio / DSP / MUSE 設定寫入仍需另行驗證；也尚未建立跨 Roon 版本、DPI 或螢幕配置的相容性承諾。完整驗證範圍 →

快速開始

1. 準備環境

2. 安裝本機依賴

git clone https://github.com/bensonmaxai/roon-desktop-mcp.git
Set-Location .\roon-desktop-mcp

$localRoot = Join-Path $env:LOCALAPPDATA 'RoonDesktopMCP'
$deps = Join-Path $localRoot 'dependencies'
$runtime = Join-Path $localRoot 'runtime'
$driver = '<absolute-path-to-cua-driver.exe>'
$roon = '<absolute-path-to-Roon.exe>'

.\scripts\setup.ps1 `
  -DependenciesDir $deps `
  -RuntimeDir $runtime `
  -DriverPath $driver `
  -RoonPath $roon

先將 $driver 與 $roon 換成你的實際執行檔位置。腳本支援 Windows PowerShell 5.1；已有依賴、只做前置檢查時可加 -SkipInstall。

3. 連接 MCP host

依 完整安裝文件與 MCP 設定範本 填入本機路徑。若要手動啟動 stdio server：

.\scripts\launch.ps1 `
  -DependenciesDir $deps `
  -RuntimeDir $runtime `
  -DriverPath $driver `
  -RoonPath $roon

啟動器預設 ROON_DESKTOP_ALLOW_INPUT=0、ROON_DESKTOP_ALLOW_FOREGROUND=0，不會註冊全域 MCP、建立常駐服務或啟動 CUA daemon。安裝後可先讓 agent 「查看 Roon 目前畫面，不送出桌面操作」。

操作與資料界線

這是給受信任本機 MCP host 使用的 stdio server，沒有 HTTP endpoint、network listener 或多使用者隔離。Windows OCR 在本機執行；截圖、OCR 與 UIA 資訊會回傳給 MCP client，若 client 使用雲端服務，這些內容也可能隨之離開本機。

音樂資料、Queue、playback、audio 與 DSP 寫入需有使用者對確切範圍的授權。相同 scope 內的非破壞性步驟可沿用既有授權；移除、刪除、清空、重設則要在動作當下確認目標。帳號、登入、密碼、授權與權限 UI 由使用者手動處理。

• user_authorized、intent 與 reconcile evidence 都是呼叫端宣告，屬於 assistant guardrail，無法隔離惡意 MCP client。raw pixel、Return 或 context menu 的語意，也可能無法由工具完整判斷。

• 導航會送出 UI input，須先啟用 ROON_DESKTOP_ALLOW_INPUT=1；呼叫端提供的 target 仍是 generic click，必須確認實際動作。

• desktop_activate 需要獨立 foreground opt-in 與使用者同意。foreground input 另須 input opt-in、先前 background refusal 或 caller 已驗證的 no-op，以及同一 action 的一次性 permit；帶到前景會改變視窗焦點。

• Journal 預設上限 10,000 筆，每筆最多 64 KiB；滿額時拒絕新的 operation ID，保留既有紀錄。operation_id 會原樣保存，請使用隨機、非識別性 ID。

• Server captures 最多保留 80 張；client-captures 副本沒有自動上限。不要把 captures、journal 或私人音樂資料提交到公開 repository。

• Dependencies、runtime 與 captures 應放在不會同步或共用的本機資料夾。腳本只檢查 dependencies / runtime 路徑文字是否含 OneDrive，無法辨識所有同步服務、junction 或 reparse point。

延伸閱讀

本專案為獨立開發的 Roon 桌面操作工具，與 Roon 官方無隸屬或背書關係。