clipzing-mcp 0.1.0

MCP server for Clipzing — talk to your clip library from Claude.

Clipzing MCP server

Connect Claude (or any MCP client) to your Clipzing account, so you can ask about your clips in plain language instead of clicking through the dashboard.

You: Which of my clips scored highest, and what's actually said in it?
You: Show me frames from that clip at 0:05, 0:20 and 0:40 — do the captions
     cover his face?
You: Using the transcript, draft a LinkedIn post in my voice.

This release is read-only. It can look at your library; it cannot edit, delete, publish or spend credits. That is deliberate — see Safety.

---

Install

Requires Python 3.10+. No dependencies.

uvx clipzing-mcp          # run without installing
# or
pipx install clipzing-mcp

Get an API key

1. Sign in to https://clipzing.com
2. Settings → API keys → Create key
3. Copy it immediately — it is shown once and cannot be recovered.

Keys expire after 90 days by default and can be revoked at any time.

Configure your client

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "clipzing": {
      "command": "uvx",
      "args": ["clipzing-mcp"],
      "env": { "CLIPZING_API_KEY": "czk_live_..." }
    }
  }
}

Claude Code:

claude mcp add clipzing --env CLIPZING_API_KEY=czk_live_... -- uvx clipzing-mcp

Restart the client, then ask it to list your clips.

---

Tools

Tool	What it does
list_clips	Your clips, newest first, with optional search
get_clip	Full detail for one clip — captions, virality score, edit state
get_clip_frames	Actual frames as images, at timestamps you choose
get_transcript	What is said, as prose or with timings
get_usage	Plan, remaining credits, render-queue state
list_jobs	Recent uploads and their processing status

get_clip_frames is the interesting one: it lets the model see your video, so it can answer things like "are the captions covering his face at 0:38?" rather than guessing from metadata.

---

Safety

Read-only. No tool in this release writes anything. Even if the model is told to — for example by text embedded in one of your own transcripts — there is no delete, publish or render tool for it to reach.

Scoped keys. A key carries explicit scopes and the server enforces them. Keys default to read only; edit, render and publish must be granted deliberately. Enforcement is server-side, so nothing running on your machine can exceed what the key allows.

Your key stays local. It is read from the environment, sent only to clipzing.com over HTTPS, and never written to disk or logs by this process.

No dependencies. This package installs nothing beyond the Python standard library, so there is no third-party code in the process that holds your key.

Revocable. Delete a key in Settings and it stops working immediately.

Bounds

Frames are capped at 8 per call and 720px wide. Larger images cost you model context without helping the model see better.

---

Troubleshooting

"CLIPZING_API_KEY is not set" — the client did not pass the env var. Check the env block in your config, then fully restart the client.

"Authentication failed" — the key is wrong, revoked, or expired. Create a new one; do not retry the old one.

"This API key is missing the 'x' scope" — the key was created without that permission. Create a new key with the scope you need.

"Clipzing is at capacity" — the render queue is saturated. Nothing was charged. Try again shortly.

Diagnostics go to stderr and appear in your client's MCP logs. Set CLIPZING_BASE_URL to point at a different environment.

---

Development

python -m pytest tests/ -q

# Drive the protocol by hand:
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | CLIPZING_API_KEY=czk_live_x python -m clipzing_mcp.server

Architecture note: this is a client, not a service. It runs on the user's machine and calls the Clipzing HTTP API — it never touches the database, so no credentials beyond the API key are ever distributed.