Metadata-Version: 2.5
Name: clipmaster-mcp
Version: 0.1.0
Summary: MCP server exposing the ClipMaster public API as tools for Claude and other MCP clients
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=2.0.0
Description-Content-Type: text/markdown

# clipmaster-mcp

MCP (Model Context Protocol) server that 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
```
