Palmier Pro — AI-native video editor via MCP

Palmier Pro is a Swift-native macOS video editor whose timeline is also an MCP server: when the app is open it exposes tools like get_timeline, add_clips, move_clips, apply_color, and generate_video at http://127.0.0.1:19789/mcp, so an external agent (Claude Code/Desktop, Cursor, Codex) or the in-app chat can edit the same project. The editor itself and the MCP server are free and open source (GPLv3); only the generative AI processing behind generate_*/upscale_media is closed source and gated behind login + subscription.

When to use this skill

Connecting an MCP client (Claude Code, Claude Desktop, Cursor, Codex) to a running Palmier Pro instance
Reading or editing a Palmier Pro project's timeline, tracks, clips, media, transcript, captions, color grade, or effects through its MCP tools
Triggering generative AI (generate_video, generate_image, generate_audio, upscale_media) inside a Palmier Pro project
Building, running, or testing the Palmier Pro Swift app from source (swift build/swift run/swift test, scripts/dev.sh)
Debugging or extending the MCP tool surface itself (Sources/PalmierPro/Agent/Tools/ToolDefinitions.swift, ToolExecutor+*.swift)

When not to use this skill

General video editing/transcoding on Linux/Windows or without Palmier Pro installed → Palmier Pro is macOS 26 + Apple Silicon only; use a portable tool (e.g. ffmpeg) instead
Generic Swift/SwiftUI app development unrelated to Palmier Pro's own codebase → use a general Swift/Xcode workflow, not this skill
The user wants an MCP-free, purely local batch video pipeline → a headless tool is a better fit; Palmier Pro's MCP server requires the GUI app open
Deep engineering-standards review of Palmier Pro's own Swift internals (concurrency, undo, actor isolation) → read AGENTS.md in the repo directly; this skill only summarizes the parts an agent-tool user needs

Instructions

Step 1: Confirm the app is open, then connect your MCP client

The MCP server only exists while Palmier Pro is running; there is no standalone server binary.

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

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

For Cursor, add to ~/.cursor/mcp.json:

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

For Claude Desktop, use the bundled one-click installer inside the app: Help → MCP Instructions → Install in Claude Desktop.

Step 2: Read the timeline before editing anything

get_timeline is the entry point for every session — it returns project settings (fps, resolution, duration), tracks with stable trackIds, clips with stable clip ids, and a canGenerate flag telling you up front whether generative tools will succeed (false means the user needs to sign in and subscribe first). Every mutation tool addresses clips/tracks by those ids, never by position. Use inspect_timeline for a narrower/windowed read on a large project instead of re-pulling the full dump every time.

See references/commands.md for the full tool list grouped by workflow area (timeline, media, clips, multicam, transcript, text/captions, color/effects, generation, meta).

Step 3: Make one coherent edit per tool call

Palmier Pro's tools are already designed around one filmmaker action per call (e.g. move_clips moves + ripples as one undoable step). Don't decompose a single user intent into a chain of lower-level calls — prefer the tool that already matches the request. Use undo to revert the most recent action if a result isn't what was expected, rather than trying to manually reconstruct prior state.

Step 4: Gate generative AI calls on `canGenerate`

generate_video/generate_image/generate_audio/upscale_media cost tokens/subscription and fail if the user isn't signed in. Check get_timeline's canGenerate (or call list_models) before batching multiple generation requests, and tell the user to sign in/subscribe first if it's false — don't loop retrying a failing generation call.

Step 5: Building/running from source (contributors)

git clone https://github.com/palmier-io/palmier-pro
cd palmier-pro
swift build
swift run
swift test

./scripts/dev.sh builds a bundled debug .app, launches it, and streams its OSLog — the fastest inner loop for MCP-tool or timeline changes. Use swift build --traits BundledSpeech for changes touching MLX, speech analysis, or transcription. If you're editing Sources/PalmierPro/Agent/ (the tool surface itself), read AGENTS.md's "Agent tool design" section first — tools must express filmmaker intent, use stable IDs, and return structured receipts, not mirror internal APIs.

Step 6: Use the wrapper for a read-only environment/connectivity check

bash .agent-skills/palmier-pro/scripts/palmier-pro.sh doctor
bash .agent-skills/palmier-pro/scripts/palmier-pro.sh mcp-status

doctor only inspects the host (macOS version, arch, app presence, Swift toolchain) and pings the local MCP endpoint — it never installs, launches, or mutates anything.

Best practices

get_timeline/inspect_timeline before any mutation — clip/track ids are stable but positions shift after every edit; never assume a previously-read index still points at the same clip.
One user intent → one tool call — the tools already model complete filmmaker actions (move-with-ripple, remove-with-linked-group); chaining low-level calls to fake a composite action duplicates logic Palmier Pro already owns and can desync from the UI's own undo grouping.
Address entities by id, not position — trackIndex/frame numbers are accepted where documented, but clip/track ids survive edits that positions don't.
Check canGenerate before spending on generation — generative calls are the only closed-source, paid part of the stack; everything else (editor, MCP server) is free.
undo over manual reconstruction — a single undo call reverts the last agent/user action cleanly; don't try to hand-compute the inverse of a move_clips/apply_effect call.
Never bypass AGENTS.md's concurrency/undo rules when touching Swift source — main-actor file I/O, unbounded task fan-out, and split undo groups are explicitly called out as review blockers in the upstream repo.

References

references/commands.md — full MCP tool reference by workflow area, plus Swift dev commands
scripts/palmier-pro.sh — read-only doctor + mcp-status checks
Palmier Pro GitHub Repository
Palmier Pro FAQ
Palmier Pro AGENTS.md — full engineering/agent-tool-design standards for contributors
Project standards: .agent-skills/skill-standardization/SKILL.md

Examples

Example 1: Connect Claude Code and make a scripted edit

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

Then, from the agent: call get_timeline to find the target clip's id, then move_clips with {"moves": [{"clipId": "...", "toFrame": 1500}]}.

Example 2: Environment check before recommending a workflow

bash .agent-skills/palmier-pro/scripts/palmier-pro.sh doctor

Example 3: Build from source and verify the MCP server comes up

git clone https://github.com/palmier-io/palmier-pro
cd palmier-pro && swift build && swift run &
bash .agent-skills/palmier-pro/scripts/palmier-pro.sh mcp-status

palmier-pro