capcut-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A local MCP (Model Context Protocol) stdio server, written in TypeScript, that exposes CapCut/Jianying video-editing operations as tools. It does not talk to CapCut directly — CapCut has no public API. Instead it's a thin HTTP client wrapper around VectCutAPI's capcut_server.py, a separately-run Python backend that generates CapCut/Jianying draft folders.

Claude  <--stdio-->  this server (src/index.ts)  <--HTTP-->  VectCutAPI's capcut_server.py (127.0.0.1:9001)

The Python backend is an external prerequisite, not part of this repo — it must be cloned and run separately (see README.md) before any tool call here will succeed.

Commands

npm install
npm run build   # tsc compile src/ -> dist/ (dist/index.js is the stdio entry point)
npm run dev      # tsx watch src/index.ts -- rebuild/rerun on save
npm run clean    # rm -rf dist
npm start        # node dist/index.js (run the built server directly)

There is no test suite or lint script configured. tsc (via npm run build) is the only correctness check — it runs with strict: true.

To actually exercise the server, the VectCutAPI Python backend must be running first (python capcut_server.py, default http://127.0.0.1:9001), and this server needs to be wired into an MCP client (Claude Desktop config, or claude mcp add capcut -- node dist/index.js). Override the backend URL with the CAPCUT_API_URL env var.

Architecture

Three files, one pattern:

• src/constants.ts — API_BASE_URL (from CAPCUT_API_URL env var, defaults to http://127.0.0.1:9001), CHARACTER_LIMIT (25000, truncates large tool responses), REQUEST_TIMEOUT_MS (60s, generous because media probing/processing is slow).

• src/schemas.ts — one Zod .strict() object schema per tool. The VectCutAPI backend accepts more optional/undocumented fields per endpoint than are worth hand-modeling, so every schema models the well-documented common fields explicitly and adds an extra_params: z.record(...) passthrough field for anything else. Adding a new field to a tool means adding it to the matching schema here — don't route new fields through extra_params if they're common enough to document.