MCP · Flow

Flow 內建 MCP server，以 Streamable HTTP 提供於 http://127.0.0.1:17996/mcp。所有 tool 都經 Command／Property 操作播放器，與 UI 和快捷鍵走同一條路。

啟用

預設關閉。啟用後重新開啟 Flow：

defaults write dev.lanstar.flow MCPServerEnabled -bool YES
defaults write dev.lanstar.flow MCPServerPort -int 18000   # 選用，預設 17996

停用：defaults delete dev.lanstar.flow MCPServerEnabled。

Flow 須保持開啟；server 在視窗就緒後才開始監聽。
port 被佔用時不會啟動，錯誤寫入系統 log（見疑難排解）。

連線

以下以 server 名稱 flow 為例；改過 MCPServerPort 時，URL 的 port 須一併修改。

CLI

claude mcp add --transport http flow http://127.0.0.1:17996/mcp   # Claude Code
codex mcp add flow --url http://127.0.0.1:17996/mcp               # Codex CLI
gemini mcp add --transport http flow http://127.0.0.1:17996/mcp   # Gemini CLI
pi mcp add flow --url http://127.0.0.1:17996/mcp                  # Pi

設定檔

Client	設定檔	內容
Cursor	`~/.cursor/mcp.json`	`{"mcpServers":{"flow":{"url":"http://127.0.0.1:17996/mcp"}}}`
VS Code（Copilot）	`.vscode/mcp.json`	`{"servers":{"flow":{"type":"http","url":"http://127.0.0.1:17996/mcp"}}}`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`{"mcpServers":{"flow":{"serverUrl":"http://127.0.0.1:17996/mcp"}}}`
opencode	`opencode.json`	`{"mcp":{"flow":{"type":"remote","url":"http://127.0.0.1:17996/mcp"}}}`

設定檔已有其他 server 時，只合併 flow 這一項。

只支援 stdio 的 client

Claude Desktop 等只支援 stdio 的 client，經 mcp-remote 轉接（Claude Desktop 的設定檔為 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{ "mcpServers": { "flow": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:17996/mcp"] } } }

其他 client 依其文件填入上述 URL。

Tools

每個 tool 執行後都回傳播放狀態，讓 agent 直接看到結果。

Tool	參數	說明
`load`	`url`：絕對路徑（可用 `~`）或 URL	開啟並開始播放，取代目前的媒體
`play`	—	繼續播放；播完後從頭播放
`pause`	—	暫停
`stop`	—	卸載媒體
`seek`	`seconds`：≥ 0；`mode`：`exact`（預設）或 `keyframe`	`exact` 顯示目標幀；`keyframe` 跳到之前的關鍵幀，較快
`set`	`property`、`value`，見下表	設定屬性
`status`	—	讀取播放狀態

`property`	`value`
`audio.volume`	0–100（%），超出範圍時取最近的值
`audio.mute`	`true`／`false`
`playback.rate`	0.25–4，超出範圍時取最近的值；變速時音調不變
`video.rotate`	順時針角度，須為 90 的倍數

參數錯誤或指令失敗時，結果標為 isError 並附原因，agent 可修正後重試。

播放狀態

{"audio.mute":false,"audio.volume":100,"playback.duration":90,"playback.paused":false,"playback.position":12.346,"playback.rate":1,"video.rotate":0}

欄位	說明
`playback.position`	目前位置（秒，精確到毫秒）
`playback.duration`	長度（秒）；未開啟媒體或長度未知時為 `null`
`playback.paused`	是否暫停
`playback.rate`、`audio.volume`、`audio.mute`、`video.rotate`	同 `set`

用 curl 測試

curl -s http://127.0.0.1:17996/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"status"}}'

不需先送 initialize，也不需 session。

安全

只監聽 127.0.0.1，其他機器連不到。
Host 與 Origin 都必須是 127.0.0.1 或 localhost，擋下瀏覽器網頁的 DNS rebinding。
沒有身分驗證：啟用後，本機任何程式都能控制 Flow，能做的事與使用者在 UI 上相同。不需要時請停用。

限制

不支援 resources、prompts 與通知；狀態變化須呼叫 status 查詢。
尚無解碼、丟幀等統計（VID-06）。
不提供截圖。

疑難排解

lsof -nP -iTCP:17996 -sTCP:LISTEN                                     # 是否在監聽
log stream --predicate 'subsystem == "Flow" AND category == "FlowMCP"' # 啟動與錯誤 log

沒有監聽：確認已啟用並重新開啟 Flow；port 被佔用時改用 MCPServerPort。
回應 403：請求的 Host 或 Origin 不是本機。