# ClipsPal MCP

Connect Claude Code, Codex, OpenCode, Cursor or another local MCP client to your videos, shorts, articles and exports.

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

## How it works

- A local stdio server bundled inside ClipsPal. No separate MCP account, API key or hosted server.
- The agent launches the bridge; the first tool call connects to the running app (and opens it on Mac).
- Video files stay on the computer. AI work uses the provider selected in ClipsPal; license and provider credentials never reach the agent.
- Needs an activated copy of ClipsPal on Mac or Windows. `ELECTRON_RUN_AS_NODE=1` runs the bridge on the app itself, so Node.js is not needed.

## Connect

Fastest for every agent below: open **Settings → Integrations** in ClipsPal, then **Add**. That page also shows commands with your exact install path.
Paths below are the default installs. Windows: replace `YOU` with your user name in JSON configs.

### Claude Code

**Run** this once:

Mac:

```bash
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"
```

Windows:

```powershell
claude mcp add --scope user clipspal `
  -e ELECTRON_RUN_AS_NODE=1 `
  '--' "$env:LOCALAPPDATA\Programs\ClipsPal\ClipsPal.exe" `
       "$env:LOCALAPPDATA\Programs\ClipsPal\resources\mcp.cjs"
```

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

### Codex

**Run** this once:

Mac:

```bash
codex mcp add clipspal \
  --env ELECTRON_RUN_AS_NODE=1 \
  -- "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal" \
     "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
```

Windows:

```powershell
codex mcp add clipspal `
  --env ELECTRON_RUN_AS_NODE=1 `
  '--' "$env:LOCALAPPDATA\Programs\ClipsPal\ClipsPal.exe" `
       "$env:LOCALAPPDATA\Programs\ClipsPal\resources\mcp.cjs"
```

**Check:** `codex mcp list` shows `clipspal`. The Codex app, CLI and IDE extension share it. Start a new session.

### OpenCode

**Add** this to your OpenCode config, keeping anything already there:

Mac — `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clipspal": {
      "type": "local",
      "command": [
        "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal",
        "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
      ],
      "environment": {
        "ELECTRON_RUN_AS_NODE": "1"
      },
      "enabled": true
    }
  }
}
```

Windows — `%USERPROFILE%\.config\opencode\opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clipspal": {
      "type": "local",
      "command": [
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\ClipsPal.exe",
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\resources\\mcp.cjs"
      ],
      "environment": {
        "ELECTRON_RUN_AS_NODE": "1"
      },
      "enabled": true
    }
  }
}
```

**Check:** `opencode mcp list` shows `clipspal` as connected.

### Cursor

**Install** with one link, then confirm in Cursor:

Mac: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=clipspal&config=eyJjb21tYW5kIjoiL0FwcGxpY2F0aW9ucy9DbGlwc1BhbC5hcHAvQ29udGVudHMvTWFjT1MvQ2xpcHNQYWwiLCJhcmdzIjpbIi9BcHBsaWNhdGlvbnMvQ2xpcHNQYWwuYXBwL0NvbnRlbnRzL1Jlc291cmNlcy9tY3AuY2pzIl0sImVudiI6eyJFTEVDVFJPTl9SVU5fQVNfTk9ERSI6IjEifX0=) · Windows: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=clipspal&config=eyJjb21tYW5kIjoiQzpcXFVzZXJzXFxZT1VcXEFwcERhdGFcXExvY2FsXFxQcm9ncmFtc1xcQ2xpcHNQYWxcXENsaXBzUGFsLmV4ZSIsImFyZ3MiOlsiQzpcXFVzZXJzXFxZT1VcXEFwcERhdGFcXExvY2FsXFxQcm9ncmFtc1xcQ2xpcHNQYWxcXHJlc291cmNlc1xcbWNwLmNqcyJdLCJlbnYiOnsiRUxFQ1RST05fUlVOX0FTX05PREUiOiIxIn19)

**Paste** into the Cursor MCP file:

Mac — `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal",
      "args": [
        "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

Windows — `%USERPROFILE%\.cursor\mcp.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\ClipsPal.exe",
      "args": [
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\resources\\mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

**Check:** Cursor Settings → **MCP** shows `clipspal` with a green dot.

### Claude Desktop

**Open** Claude Desktop → **Settings → Developer → Edit Config** and add:

Mac — `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal",
      "args": [
        "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

Windows — `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\ClipsPal.exe",
      "args": [
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\resources\\mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

**Quit and reopen** Claude Desktop. The tools menu in a new chat lists `clipspal`.

### Windsurf

**Add** to the Windsurf MCP config:

Mac — `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal",
      "args": [
        "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

Windows — `%USERPROFILE%\.codeium\windsurf\mcp_config.json`:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\ClipsPal.exe",
      "args": [
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\resources\\mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

**Check:** press **Refresh** in Windsurf’s MCP panel; `clipspal` lists its tools.

### Other apps

Any app that runs a local (stdio) MCP server works. Most take this JSON:

Mac:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "/Applications/ClipsPal.app/Contents/MacOS/ClipsPal",
      "args": [
        "/Applications/ClipsPal.app/Contents/Resources/mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

Windows:

```json
{
  "mcpServers": {
    "clipspal": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\ClipsPal.exe",
      "args": [
        "C:\\Users\\YOU\\AppData\\Local\\Programs\\ClipsPal\\resources\\mcp.cjs"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}
```

Apps with a form instead ask for three fields:

Mac:

```
Command      /Applications/ClipsPal.app/Contents/MacOS/ClipsPal
Arguments    /Applications/ClipsPal.app/Contents/Resources/mcp.cjs
Environment  ELECTRON_RUN_AS_NODE=1
```

Windows:

```
Command      C:\Users\YOU\AppData\Local\Programs\ClipsPal\ClipsPal.exe
Arguments    C:\Users\YOU\AppData\Local\Programs\ClipsPal\resources\mcp.cjs
Environment  ELECTRON_RUN_AS_NODE=1
```

## Try asking

- “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.”

## Rules for agents

ClipsPal is a local talking-head video editor. Start with videos_list and video_get; latest means createdAt. Full videos and shorts have separate ids. transcript_get pages source words or kept words in playback order; source seconds and edited output seconds are different. Existing media and compressed proxies can be inspected through video_get/assets_list; do not assume missing originals make a video unavailable. Duplicate a video before experiments. video_edit and video_cut require the latest revision and never rewrite footage. AI and exports run in the app: background tools return a job id, wait caps at 50 seconds, and job_get carries real errors/results. One MCP job per video at a time; the app may also refuse work while its media lane is busy. AI follows the video’s provider or Settings. Read the saved output before claiming completion, and do not call an incomplete edit or queued motion job finished. Article export creates local files, never publishes. Agents cannot read license credentials, run arbitrary shell commands, access browser cookies, start microphone/screen recording, or delete videos through this surface. Connection setup uses Settings → Integrations. Use the owner’s existing authorization; do not add approval checkpoints for requested edits.

- Tools marked **background** return at once. Call `wait` (returns within 50 s), repeat while jobs run, then `status`.
- Export writes local files only. It does not publish to websites or social networks.
- Video ids come from `videos_list`, source ids/revisions from `video_get`, and article ids from `articles_get`.

## Workflows

| Goal | Calls |
|---|---|
| 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` |

## Troubleshooting

| Problem | Fix |
|---|---|
| “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. |

## Tools (21)

### Read

#### `status` (read)

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

#### `videos_list` (read)

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

#### `video_get` (read)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |

#### `transcript_get` (read)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `mode` | source \| edited | Default edited. |
| `offset` | integer |  |
| `limit` | integer |  |

#### `assets_list` (read)

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

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |

#### `articles_get` (read)

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

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `articleId` | string | Optional article id. |

### Edit

#### `video_duplicate` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `name` | string | Optional name for the copy. |

#### `video_edit` (write)

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

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `revision` * | string | Current revision from video_get. Stale revisions fail without changing the video. |
| `patch` * | object | Fields to change. |

#### `video_cut` (write)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `revision` * | string | Current revision from video_get. Stale revisions fail without changing the video. |
| `sourceId` * | string | Source id from video_get. |
| `start` * | number | Start in source seconds. |
| `end` * | number | End in source seconds; greater than start. |
| `included` * | boolean | false cuts; true restores. |

#### `director_request` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `instruction` * | string | What to change. |

#### `video_analyze` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `instruction` | string | Optional editing request. |

#### `transcript_edit` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `instruction` * | string | Corrections or vocabulary. |

### Create

#### `shorts_create` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `instruction` | string | Optional angle, audience or length request. |
| `count` | integer | Default 1. |

#### `article_create` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `direction` | string | Optional article angle, audience or brief. |

#### `article_revise` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `articleId` * | string | Article id from articles_get. |
| `instruction` * | string | Requested changes. |

#### `chapters_generate` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `feedback` | string | Optional chapter feedback. |

### Export

#### `video_export` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `options` | object | Export choices. |

#### `article_export` (write, background)

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.

| Param | Type | Notes |
|---|---|---|
| `recordingId` * | string | Video id from videos_list. Full videos and shorts have separate ids. |
| `articleId` * | string | Article id from articles_get. |

### Jobs

#### `job_get` (read)

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

| Param | Type | Notes |
|---|---|---|
| `jobId` * | string | Job id returned by a background tool. |

#### `wait` (read)

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.

| Param | Type | Notes |
|---|---|---|
| `jobId` | string | Optional MCP job id. |
| `timeoutMs` | integer | Milliseconds, default 1000, at most 50000. |

#### `job_cancel` (write)

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.

| Param | Type | Notes |
|---|---|---|
| `jobId` * | string | MCP job id. |

`*` = required.