On this page

Docs · MCP

Connect your AI agent

Claude Code, Codex, OpenCode, Cursor and any other MCP app can run ClipsPal for you: read your videos and transcripts, edit a copy, create shorts and articles, and export the results.

MCP is included in the next app update. The current public download does not include it yet.

View as Markdown

Runs on your computer

A local connection to the editor. No separate MCP account or API key.

21 tools

Your videos, edits, shorts, articles and local exports.

One step to set up

Open Settings → Integrations and press Add, or paste one command.

Connect

Pick your agent. ClipsPal needs to be installed and activated.

Claude Code

1
One click: in ClipsPal open Settings → Integrations and press Add next to it. The app writes the config and fixes it after you move the app.

Or run this once:

Terminal

claude mcp add --scope user clipspal \
  -e ELECTRON_RUN_AS_NODE=1 \
  -- "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal" \
     "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"

3
Check: claude mcp list shows clipspal. Start a new Claude Code session.

Try asking

Start a new session in your agent, then ask in plain words.

“Show me my latest video and its edited transcript.”
“Duplicate my latest video and make one vertical short from it.”
“Create an article from my video for people new to the topic.”
“Revise the article with a stronger opening and shorter paragraphs.”
“Export the short and its subtitles to my video folder.”

How long jobs run

Media copying, AI work and exports run inside the app. The tool that starts one answers at once.
The agent follows along with wait, which returns within 50 seconds, then job_get. It repeats until the job is done.
Use job_get for progress and results, and job_cancel to request cancellation.
AI generation uses the provider selected for that video. Exported files stay on your computer.

Workflows

The calls an agent makes for common jobs.

Inspect a video

videos_list→video_get→transcript_get→assets_list

Try a reversible cut

video_duplicate→wait→job_get→video_get→video_cut→video_get

Create a short

shorts_create→wait→job_get→videos_list→video_get

Write an article

article_create→wait→articles_get

Revise an article

article_revise→wait→articles_get

Create chapters

chapters_generate→wait→video_get

Export locally

video_export→wait→job_get

Tools (21)

Open a tool for its full description and parameters.

Read

statusReadCurrent app state and jobs started through MCP in this app session.

Current app state and jobs started through MCP in this app session. Errors and incomplete work are reported explicitly.

No parameters.

videos_listReadList saved videos and shorts, newest first.

List saved videos and shorts, newest first. Latest means createdAt, not the last edited video.

No parameters.

video_getReadRead the saved edit, source and compressed media paths, timeline, settings, articles and current revision.

Read the saved edit, source and compressed media paths, timeline, settings, articles and current revision. Waveforms and word transcripts are omitted; use transcript_get for words. File paths refer to this computer.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.

transcript_getReadRead source words or the kept words in playback order.

Read source words or the kept words in playback order. Source start/end are seconds within each source. Edited words additionally have outputStart seconds in the finished video. Pages cap at 2,000 words; use offset/limit until nextOffset is null.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
modesource | edited: Default edited.
offsetinteger
limitinteger

assets_listReadList the video’s reusable Images & videos media.

List the video’s reusable Images & videos media. Existing source and proxy paths are available through video_get.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.

articles_getReadRead saved article titles, blocks, media references and editorial history.

Read saved article titles, blocks, media references and editorial history. Optional articleId reads one article.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
articleIdstring: Optional article id.

Edit

video_duplicateWriteBackgroundMake an independent saved edit and copy its working media, preserving external originals.

Make an independent saved edit and copy its working media, preserving external originals. Use a copy for experiments. The finished job returns the new video id/revision. Media copying cannot be cancelled; wait for it to finish. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
namestring: Optional name for the copy.

video_editWriteChange only the supplied name, brief, playback speed or AI choice.

Change only the supplied name, brief, playback speed or AI choice. Requires the current revision. Original media files are not rewritten.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
revisionrequiredstring: Current revision from video_get. Stale revisions fail without changing the video.
patchrequiredobject: Fields to change.

video_cutWriteRemove (included=false) or restore (included=true) a source-time range in the edit.

Remove (included=false) or restore (included=true) a source-time range in the edit. Reversible; never changes original/compressed files. Read source timing with transcript_get and the current revision with video_get. Do not cut based only on uncertain transcript timing.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
revisionrequiredstring: Current revision from video_get. Stale revisions fail without changing the video.
sourceIdrequiredstring: Source id from video_get.
startrequirednumber: Start in source seconds.
endrequirednumber: End in source seconds; greater than start.
includedrequiredboolean: false cuts; true restores.

director_requestWriteBackgroundAsk Director to edit the video, correct its transcript or create shorts.

Ask Director to edit the video, correct its transcript or create shorts. The host follows the same routed actions as the app. Motion work may be queued separately; inspect saved proposals before claiming it finished. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
instructionrequiredstring: What to change.

video_analyzeWriteBackgroundRun the existing automatic editing pipeline, optionally with an editing instruction.

Run the existing automatic editing pipeline, optionally with an editing instruction. Can change cuts, punch-ins, sounds and visual requests; duplicate first for experiments. An incomplete pass is not success. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
instructionstring: Optional editing request.

transcript_editWriteBackgroundUse the chosen AI to correct transcript text following your instruction.

Use the chosen AI to correct transcript text following your instruction. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
instructionrequiredstring: Corrections or vocabulary.

Create

shorts_createWriteBackgroundCreate one to five vertical shorts from the kept video, inheriting its edits and media.

Create one to five vertical shorts from the kept video, inheriting its edits and media. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
instructionstring: Optional angle, audience or length request.
countinteger: Default 1.

article_createWriteBackgroundCreate an article from the kept transcript through the same planning, drafting and independent review used by the app.

Create an article from the kept transcript through the same planning, drafting and independent review used by the app. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
directionstring: Optional article angle, audience or brief.

article_reviseWriteBackgroundRevise an existing saved article with feedback.

Revise an existing saved article with feedback. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
articleIdrequiredstring: Article id from articles_get.
instructionrequiredstring: Requested changes.

chapters_generateWriteBackgroundGenerate or revise YouTube chapters for the finished video; read saved chapters with video_get.

Generate or revise YouTube chapters for the finished video; read saved chapters with video_get. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
feedbackstring: Optional chapter feedback.

Export

video_exportWriteBackgroundExport the saved edit through the app’s export queue.

Export the saved edit through the app’s export queue. Options omitted uses the app defaults. Empty resolutions with includeSrt=true and burnCaptions=false writes subtitles only. Exported files get unique names; reads never replace source files. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
optionsobject: Export choices.

article_exportWriteBackgroundExport an existing article’s text, HTML and referenced media to its video folder.

Export an existing article’s text, HTML and referenced media to its video folder. Does not publish to any website or social network. Returns a job id immediately. Call wait or job_get until status is done/error/cancelled. AI uses the video’s provider or Settings.

recordingIdrequiredstring: Video id from videos_list. Full videos and shorts have separate ids.
articleIdrequiredstring: Article id from articles_get.

Jobs

job_getReadRead one MCP job’s progress, result or error.

Read one MCP job’s progress, result or error. Job ids last for this app session; saved edits remain after restart.

jobIdrequiredstring: Job id returned by a background tool.

waitReadWait up to 50 seconds for one job to finish, or for any job update when jobId is omitted.

Wait up to 50 seconds for one job to finish, or for any job update when jobId is omitted. Call again while status is running. Timeout never cancels work.

jobIdstring: Optional MCP job id.
timeoutMsinteger: Milliseconds, default 1000, at most 50000.

job_cancelWriteRequest cancellation of a running MCP job.

Request cancellation of a running MCP job. Already saved edits remain. Cancellation targets this video’s operation; wait for its final status before starting another.

jobIdrequiredstring: MCP job id.

Troubleshooting

“ClipsPal is not running and could not be opened.”

Open ClipsPal, then ask again.

“Activate ClipsPal first.”

Enter your license key in the app.

The agent does not see the tools

Start a new agent session. Check its MCP list command.

It stopped after moving or reinstalling the app

Open Settings → Integrations in ClipsPal and press Update next to the agent.

A long job seems stuck

Call job_get for its real progress or error. wait returns within 50 seconds and never cancels the job.

The video changed since I read it

Read video_get again and use its new revision. Review the change before retrying an edit.

Still stuck? Chat with us.