zapcap-mcp

Model Context Protocol server for the ZapCap video captioning API. Gives AI agents (Claude Desktop, Cursor, Claude Code, any MCP host) zero-code access to ZapCap: upload a video, caption it, translate it, render it in any template.

What you can do

Ask your agent things like:

• "Caption this video in Spanish, French and German using the default template."
• "Render this video in 5 different ZapCap templates so I can compare."
• "Transcribe this URL and fix the brand name spellings in the transcript before rendering."
• "How much ZapCap credit do I have left?"

The MCP exposes ZapCap's API as primitives. The LLM composes the workflow.

Install

# Requires Node.js >= 20
npm install -g zapcap-mcp

Or run on demand via npx zapcap-mcp — no install needed.

Configure

Get an API key at platform.zapcap.ai/dashboard/api-key.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zapcap": {
      "command": "npx",
      "args": ["-y", "zapcap-mcp"],
      "env": {
        "ZAPCAP_API_KEY": "your-zapcap-api-key"
      }
    }
  }
}

Restart Claude Desktop. The zapcap tools will appear in the tool picker.

Cursor / Claude Code / other MCP hosts

Use the same stdio command (npx -y zapcap-mcp) with ZAPCAP_API_KEY in the environment.

Environment

| Variable | Required | Default | Notes | | ----------------------- | -------- | ----------------------- | ---------------------------------------------- | | ZAPCAP_API_KEY | yes | — | Your ZapCap API key. | | ZAPCAP_API_BASE_URL | no | https://api.zapcap.ai | Override for staging or self-hosted gateways. |

Tools

| Tool | What it does | | ------------------------ | ------------------------------------------------------------------------ | | upload_video_by_url | Upload a video from a public URL → returns videoId. | | upload_video_from_path | Stream a local video file (absolute path) to ZapCap → returns videoId. | | list_templates | List all caption templates available to the account. | | get_user_balance | Pre-flight check for remaining USD credit balance. | | create_video_task | Start a captioning/render task. Supports transcriptTaskId (fan-out), bring-your-own transcript, dictionary (term-biasing), renderOptions, exportSettings, transcribeSettings (b-roll), webhook notification, and ttl. | | get_video_task | One-shot task status check. | | wait_for_task | Poll a task with exponential backoff until it's done. | | update_transcript | Edit a transcript before approval (spelling fixes, emoji additions). | | approve_transcript | Unblock rendering on a manually-reviewed transcript. |

The fan-out pattern (5 languages / 5 templates)

Caption one video in N languages without re-transcribing it N times:

1. create_video_task(videoId, templateId, language='en')                    -> taskA
2. wait_for_task(videoId, taskA.taskId, waitFor='transcriptionCompleted')
3. For each lang in [es, fr, de, ja, pt]:
     create_video_task(videoId, templateId,
                       transcriptTaskId=taskA.taskId,
                       translateTo=lang,
                       autoApprove=true)                                    -> 5 render tasks
4. wait_for_task(videoId, taskN) on each in parallel.

Same shape for 5-templates — vary templateId instead of translateTo. The transcriptTaskId parameter is the key — it tells ZapCap to reuse an existing transcript instead of paying to transcribe again.

File uploads

Two ingress paths:

• upload_video_by_url — ZapCap fetches the video from a publicly reachable HTTP(S) URL.
• upload_video_from_path — the MCP streams a local file from disk directly to POST /videos via multipart. The file is read with fs.openAsBlob and piped through undici.fetch, so the bytes never get buffered into memory or into the LLM context. The path must be absolute. Best for small-to-medium files; for very large files prefer a presigned-URL flow.

Development

git clone https://github.com/ZapCapAI/zapcap-mcp
cd zapcap-mcp
npm install
ZAPCAP_API_KEY=... npm run dev    # tsx, hot reload
npm run build                      # compile to dist/
npm test                           # unit tests

License

MIT