clipzing-mcp 0.2.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

Configure your client

There is no key to copy. On first run the server prints a short code, opens your browser, and you approve the connection while already signed in — so no secret is ever displayed, pasted, or written into your config file.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "clipzing": {
      "command": "uvx",
      "args": ["clipzing-mcp"]
    }
  }
}

Claude Code:

claude mcp add clipzing -- uvx clipzing-mcp

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

Approve the connection

The first request triggers pairing:

  ┌─────────────────────────────────────────────┐
  │  Connect Clipzing — code  BCDF-2345       │
  └─────────────────────────────────────────────┘
  Opening https://clipzing.com/link?code=BCDF-2345
  Approve there, and this will continue automatically.

(This goes to stderr, not stdout — stdout carries the MCP protocol.)

Sign in if you are not already, check that the client name and code match what your terminal shows, and choose what the agent may do. Read is granted by default; edit, render and publish are opt-in, and your plan caps what can be offered. Approving stores the credential in your OS keychain (macOS Keychain, or a 0600 file elsewhere) — never in your project.

The credential expires after 90 days and can be revoked at any time from Settings → API keys. Revoking takes effect immediately.

If you would rather manage a key yourself

Setting CLIPZING_API_KEY skips pairing entirely. This suits CI and servers, where no browser exists. It is not the recommended path for a workstation: it puts a long-lived secret in an environment file that is easy to commit.

---

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

Pairing never completes — the code lives for 10 minutes. If it expired, restart the client for a fresh one. Approval requires a signed-in browser session; a code alone grants nothing.

"Agent access is not included on your current plan" — MCP is a paid feature. Starter allows read and edit; Pro adds render and publish.

"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.