Palmier Pro MCP 集成实战：让 Claude、Codex 与 Cursor 直接驱动 macOS 视频时间线

Palmier Pro 是一款为 AI 而生、用 Swift 从零构建的原生 macOS 视频编辑器，它通过内置的 MCP（Model Context Protocol）服务器把“编辑器的时间线”直接开放给外部 Agent，让 Claude、Codex、Cursor 等工具能像人一样读取项目、剪辑素材、生成媒体并管理轨道。本文以官方 README（葡萄牙语版 docs/readme/README.pt-BR.md）为核心骨架，结合仓库源码逐项拆解 MCP 服务器的连接方式、工具能力与底层实现，帮助读者把任意支持 MCP 的 Agent 接入自己的剪辑工作流。

一、项目定位：为 AI 而生的原生视频编辑器

Palmier Pro 的核心定位可以概括为三句话：

• Swift 原生视频编辑器：项目从零开始用 Swift 构建，以 Premiere Pro 为参照系，但把 AI 深度融入了剪辑工作流（见仓库根目录 README.md）。
• 内置生成式 AI：可以直接在时间线编辑器内调用 Seedance、Kling、Nano Banana Pro 等一线视频/图像生成模型，完成文生视频、图生视频、超分等任务。
• 与 Agent 深度集成：既可通过 MCP 连接 Claude、Codex、Cursor 等外部 Agent，也可使用应用内自带 Agent 在同一项目上协同工作。

从源码看，这一“编辑器 + Agent”的双通道架构落在 Sources/PalmierPro/Agent 目录下：Clients/ 负责模型客户端（含应用内 Agent 使用的 PalmierClient.swift，通过 Bearer JWT 认证调用后端流式接口），MCP/ 负责本地 MCP 服务器，Tools/ 则集中定义了供 Agent 调用的全部工具。

二、MCP 服务器：一个跑在本地的 HTTP 端点

当 Palmier Pro 应用处于打开状态时，它会自动在本地暴露一个 MCP 服务器，端点地址为：

http://127.0.0.1:19789/mcp

端口与监听策略（源码级佐证）

这一地址并非 README 的“纸面承诺”，而是写死在源码中的硬性约定：

• 端口常量定义在 MCPService.swift：static let port: UInt16 = 19789；
• 监听器实现位于 MCPHTTPServer.swift，使用 Network 框架的 NWListener 建立 TCP 监听；
• 关键安全设计：服务器只绑定 IPv4 回环地址 127.0.0.1（params.requiredLocalEndpoint = .hostPort(host: "127.0.0.1", ...)，见 MCPHTTPServer.swift），源码注释明确说明“服务器永远无法从局域网被访问”，因此外部网络上的机器无法连入你的时间线。

此外，服务器自带会话治理机制：单会话空闲上限 3600 秒、并发会话上限 32 个（见 MCPHTTPServer.swift），超限会按空闲时间逐出最旧会话，被逐出的客户端下一次请求会得到 404，随后自动重新初始化（pruneIdleSessions 与 evictSession 实现见同文件 L219-L235）。

服务器支持的能力声明

服务器在初始化时对外声明的能力（来自 MCPService.swift）：

• tools：支持 listChanged 通知（当工具清单变化时向客户端推送 tools/list_changed，实现见 MCPHTTPServer.swift）；
• resources：注册了两个只读资源——palmier://models/video 与 palmier://models/image，用于向 Agent 返回可用 AI 视频/图像生成模型及其能力 JSON（见 MCPService.swift）。

服务器名称为 palmier-pro，版本号 1.0.0，并携带一套详尽的系统指令（AgentInstructions.serverInstructions + AgentInstructions.projectNavigation，见 AgentInstructions.swift），用于约束 Agent 的剪辑行为。

三、连接配置：四种主流客户端的接入方式

官方 README 提供了四种接入方式，以下命令与配置均以仓库实际内容为准，可直接复制使用。

3.1 Claude Code（命令行）

在终端执行一次即可完成注册：

claude mcp add --transport http palmier-pro http://127.0.0.1:19789/mcp

该命令在应用内的 Help → MCP Instructions 面板中也会原样展示（源码见 MCPInstructionsPane.swift，其中 mcpEndpoint 由 MCPService.port 动态拼接，保证与真实端口永远一致）。

3.2 Codex（OpenAI 命令行工具）

codex mcp add palmier-pro --url http://127.0.0.1:19789/mcp

同样可以在应用内 Help → MCP Instructions → Codex 小节中直接复制（见 MCPInstructionsPane.swift）。

3.3 Cursor（图形 IDE）

最省事的方式是在应用内执行 Help → MCP Instructions → Install in Cursor：应用会通过 cursor://anysphere.cursor-deeplink/mcp/install 深链一键写入配置（深链 URL 的构造逻辑见 MCPInstructionsPane.swift）。

也可以手动把以下 JSON 添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "palmier-pro": {
      "type": "http",
      "url": "http://127.0.0.1:19789/mcp"
    }
  }
}

这段 JSON 与应用内“Manual setup”折叠面板展示的内容完全一致（见 MCPInstructionsPane.swift）。

3.4 Claude Desktop（桌面客户端）

Palmier Pro 随应用捆绑了一个 mcpb 打包的桌面扩展包，可在 Claude Desktop 中一键安装。入口同样是应用内 Help → MCP Instructions → Install in Claude Desktop，应用会定位到随包资源 palmier-pro.mcpb 并用 NSWorkspace 唤起 Claude Desktop 完成安装（见 MCPInstructionsPane.swift）。

从 mcpb/manifest.json 可以看到该扩展包的本质：一个 manifest_version: "0.4"、名为 palmier-pro、描述为“Edit your videos with Palmier Pro from Claude Desktop”的 Node 型 mcpb 应用，入口为 server/index.js，运行环境要求 Node ≥ 18。

值得一提的底层细节：Claude Desktop 走的是 stdio 传输，而 Palmier Pro 暴露的是 HTTP 端点，因此 mcpb/server/index.js 实际扮演了一个 stdio → HTTP 桥接层（shim）：它把 Claude Desktop 的 JSON-RPC 消息转发到 http://127.0.0.1:19789/mcp，维护会话 ID 与协议版本，遇到会话过期或连接中断时以指数退避（500ms→5s）自动重连并重放未送达的请求，同时用独立的 GET 流接收服务器的 tools/list_changed 通知。这个文件把“本地 HTTP 服务器”与“桌面客户端 stdio 通道”两种传输模型无缝衔接了起来。

四、Agent 能做什么：完整的工具能力矩阵

接入 MCP 后，Agent 拿到的是一套覆盖剪辑全流程的工具集。全部工具定义在 ToolDefinitions.swift，mcpServer 清单（all + [manageProject]，见该文件 L1255）至少包含以下分组：

分组	代表工具	典型用途
项目	manage_project、set_project_settings、export_project、manage_exports	打开/创建/关闭项目、改帧率分辨率画幅、排队导出
时间线	get_timeline、inspect_timeline、create_timeline、set_active_timeline、manage_markers	读取轨道结构、合成帧预览、创建/复制时间线、管理标记
素材库	get_media、inspect_media、search_media、import_media、capture_frame、organize_media	列出素材、按内容语义搜索、导入外部媒体、抓帧、整理文件夹
剪辑	add_clips、insert_clips、move_clips、remove_clips、split_clips、ripple_delete_ranges、swap_clip_media、set_clip_properties、set_keyframes、copy_clip_settings、apply_layout、sync_clips、undo	放置/插入/移动/删除/切割片段、波纹删除、换素材、设属性、打关键帧、复制设置、布局、音画同步
多机位	manage_multicam、change_cam、get_multicam	建组、切机位、读组结构
字幕转录	get_transcript、remove_words、remove_silence、detect_beats	读逐词字幕、删语气词、去静音、检测节拍
文字与字幕	add_texts、update_text、add_captions	加文字、改样式、自动生成字幕
色彩与特效	apply_color、apply_effect、inspect_color、denoise_audio	调色（含色轮/曲线/色相曲线/LUT）、特效栈、示波器测量、音频降噪
生成	list_models、generate_video、generate_image、generate_audio、upscale_media	列出模型、生成视频/图像/音频、超分
元能力	send_feedback、read_skill、manage_skills	反馈缺陷、读取技能、管理技能

从工具描述中可以提炼出几个对 Agent 非常关键的约定（这些约定同时写入了 AgentInstructions.swift 的服务器指令中）：

• 时间单位体系：时间线上的位置一律使用“项目帧”（startFrame、endFrame、gaps、ranges），而素材源的位置一律使用“秒”（source、搜索命中、素材字幕与时长）。工具负责单位换算，Agent 无需自行乘除 fps。
• 轨道模型：轨道有序且有类型（视频/音频），索引 0 渲染在最上层；manage_tracks 优先使用稳定的 trackId 而非易变的索引；视频片段关联的音频以嵌套的 audio: {id, track, …} 形式折叠呈现。
• 会话工作流：建议每个会话先调用一次 get_timeline；每次编辑后依据工具返回的增量 delta（clips、shifted、removedClipIds、markers、createdTracks、notes）就地修补自身模型，而不是反复重读整个时间线。
• 生成类工具的成本约束：generate_* 与 upscale_media 真实计费且不可撤销，服务器指令要求 Agent 先调用 list_models 确认模型能力，并在提交前向用户提案确认；get_timeline 还会返回 canGenerate 标志，为 false 时生成工具会失败（提示用户登录并订阅）。

五、底层原理：一次 MCP 工具调用的完整链路

以“Agent 调用 add_clips 在时间线上放一段素材”为例，完整链路如下（全部有源码佐证）：

1. HTTP 接入：客户端向 http://127.0.0.1:19789/mcp 发起 POST 请求，请求体为 JSON-RPC 消息。服务器在 MCPHTTPServer.swift 的 process/handle 中完成 HTTP 解析（支持跨多个 TCP 读取累积请求体、按 Content-Length 判定完整性）与路由：携带 Mcp-Session-Id 头走有状态会话；POST initialize 创建新会话；其余走无状态的 fallback 通道（兼容普通 curl 探测）。

2. 工具分发：MCPService.registerTools 把 ToolDefinitions.swift 中的每个 AgentTool 注册为 MCP Tool（名称、描述、JSON Schema 输入），并挂载 ListTools 与 CallTool 两个方法处理器（见 MCPService.swift）。

3. 参数桥接与执行：CallTool 的参数先经 ToolArgsBridge 从 MCP Value 转为普通字典，再交给 ToolExecutor.execute(name:args:source:) 执行（source 为 "mcp"，见 MCPService.swift）。ToolExecutor 的实现分布在 Sources/PalmierPro/Agent/Tools/ToolExecutor*.swift 系列文件中，按能力域拆分（+Timeline、+Clips、+Color、+Generate、+Export 等）。

4. 结果回传：执行结果统一封装为 ToolResult（支持文本与 base64 图片两种内容块，见 ToolResult.swift），再转换为 MCP CallTool.Result；SSE 流式响应通过 Connection: close 定界（见 MCPHTTPServer.swift）。

仓库中还配套了大量针对这些工具的测试用例，例如 Tests/PalmierProTests/Agent/ 下的 TimelineToolsTests.swift、SetClipBlendModeTests.swift、MCPVolumeKeyframeTests.swift、MCPTextFillModeTests.swift 等，可直接作为理解各工具行为边界的参考。

六、FAQ：版本、费用与平台兼容性

Palmier Pro 哪些版本是开源的？

README 明确说明：v0.7.6 及之前的发布版本、以及对应的历史源码（last-gpl-source 分支）在 GPLv3 许可下开源可用；v0.7.6 之后的二进制版本转为闭源专有，其源码不再公开。当前仓库保留历史源码并承载最新的二进制发布与更新元数据（见根目录 README.md 顶部声明）。

免费吗？

编辑器本体免费：无需登录即可下载并使用，可作为纯视频剪辑工具（类比 CapCut 或 Adobe Premiere 的使用方式）；MCP 服务器同样免费开放，可立即配合 Claude Code、Claude Desktop 或 Cursor 体验“Agent 操作时间线”。生成式 AI 能力（generate_*、超分等）需要登录账号并订阅。

支持哪些平台？

仅支持 Apple Silicon（M 系列）Mac 上的 macOS 26（Tahoe）或更高版本，无 Intel 支持。这也是 README 中“下载”徽章下方注明的前提条件。

七、许可与社区

仓库源码按 GPLv3 发布（见 LICENSE）；v0.7.6 之后的二进制版本受专有许可约束（见 BINARY_LICENSE.md）。官方建议的沟通渠道包括 Discord 社区、X/Twitter 账号 @Palmier_io、Instagram 以及反馈邮箱 [e-mail]（详见葡萄牙语 README 的“Comunidade e suporte”小节，docs/readme/README.pt-BR.md）。此外，仓库不再接受代码贡献，已发布的 GPLv3 源码仍可供使用、修改与再分发。