# clipmaster-mcp

mcp-name: io.github.n0Sp00n/clipmaster-mcp

MCP (Model Context Protocol) server for [ClipMaster](https://clipmaster.app) —
AI video clipping at [clipmaster.app](https://clipmaster.app). It exposes the
ClipMaster public API as tools, so Claude Desktop, Claude Code, and any MCP client can ingest videos,
monitor processing, browse clips, trigger exports, and schedule posts.

- Talks ONLY to the public REST API (`https://api.clipmaster.app/api/v1`) with
  the user's API key — no database access, no internal services.
- Ingestion is URL-only by design (streaming a local file through an LLM tool
  call is impractical). Account management (keys, billing, OAuth connects) is
  excluded; the API rejects those routes for key auth anyway.

## Requirements

- Python 3.10+
- A ClipMaster API key (paid plans): web app → Settings → API access

## Install

From this repo checkout:

```bash
pipx install ./clipmaster-mcp
# or, without installing:
uvx --from ./clipmaster-mcp clipmaster-mcp
```

## Configure

| Env var | Required | Meaning |
|---|---|---|
| `CLIPMASTER_API_KEY` | yes* | Your `cm_live_…` API key |
| `CLIPMASTER_API_BASE` | no | Override the API base URL (default `https://api.clipmaster.app/api/v1`) |

*Instead of the env var you can put the key in `~/.config/clipmaster/key` —
this keeps it out of client config files and shell history:

```bash
mkdir -p ~/.config/clipmaster && printf '%s' 'cm_live_...' > ~/.config/clipmaster/key && chmod 600 ~/.config/clipmaster/key
```

The env var wins when both are set.

### Claude Code

```bash
claude mcp add clipmaster -e CLIPMASTER_API_KEY=cm_live_... -- clipmaster-mcp
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clipmaster": {
      "command": "clipmaster-mcp",
      "env": { "CLIPMASTER_API_KEY": "cm_live_..." }
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `ingest_youtube(url, orientation?, user_query?, compilation_format?)` | Import a YouTube video, start clip generation |
| `get_status(project_id)` | Processing progress / state |
| `list_projects()` | The user's projects |
| `list_clips(project_id)` | Generated clips with AI metadata |
| `get_clip(project_id, clip_id)` | Full detail for one clip |
| `trigger_export(project_id, clip_id)` | Render a clip with its saved settings (charges tokens) |
| `get_export_status(export_id)` | Poll an export; completed → temporary `download_url` |
| `list_compilations(source_project_id?)` / `get_compilation(id)` | Cross-project clip collections |
| `list_social_accounts()` | Connected channels for scheduling |
| `schedule_post(...)` | Schedule an export to publish (idempotent on retry) |
| `list_scheduled_posts(from_date, to_date)` | Posting calendar range |

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -e ./clipmaster-mcp pytest
.venv/bin/pytest clipmaster-mcp/tests -q
```