capcut-mcp

An MCP server that lets Claude (or any MCP client) build CapCut projects: video/image clips, audio, text, SRT subtitles, transitions, animations, filters and keyframes.

CapCut has no public API. This server does not control the CapCut app. It writes draft projects to disk (via pyJianYingDraft), which you then open in CapCut. Not affiliated with ByteDance or CapCut.

Install

git clone https://github.com/yeroshalmiariel-ai/capcut-mcp
cd capcut-mcp
pip install -e .

Requires Python 3.9+. If pip install pyJianYingDraft fails on your platform, install it from source: pip install git+https://github.com/GuanYixuan/pyJianYingDraft.git.

Related MCP server: capcut-mcp

Configure

Point the server at your CapCut drafts folder with CAPCUT_DRAFTS_DIR (it also tries the default location on Windows and macOS):

Claude Code

claude mcp add capcut -e CAPCUT_DRAFTS_DIR="/path/to/com.lveditor.draft" -- capcut-mcp

Claude Desktop / other clients — see mcp.json.example.

Local URL (no secret)

For a client on the same computer that wants a URL instead of launching a subprocess (for example Claude Code), run the server in local-only mode:

capcut-mcp --http --no-secret --port 8000
claude mcp add --transport http capcut http://127.0.0.1:8000/mcp

This mode only accepts connections from your own computer and only requests addressed to localhost. It refuses to start on any other --host and can't be combined with a secret. Don't put a tunnel in front of it. claude.ai connectors run in the cloud and can't reach 127.0.0.1; use the remote mode below for those.

Get a URL with sign-in (claude.ai connector)

claude.ai connectors run in the cloud, so the server must be reachable from the internet. Sign-in mode protects it with a password login page (OAuth): claude.ai sends you to your own server's login page, and only gets access after you enter the password. Run it on the computer that has CapCut:

# 1. expose a local port with a tunnel and note the https address it prints (either one)
cloudflared tunnel --url http://127.0.0.1:8000
ngrok http 8000

# 2. in another terminal, start the server with that address and a password of your choice
export CAPCUT_DRAFTS_DIR="/path/to/com.lveditor.draft"
export CAPCUT_MCP_PASSWORD="choose-a-long-password"
capcut-mcp --http --port 8000 --public-url https://YOUR-TUNNEL-ADDRESS
# prints: Connector URL: https://YOUR-TUNNEL-ADDRESS/mcp

In claude.ai go to Settings -> Connectors -> Add custom connector, paste the connector URL, and connect. You'll be sent to the login page; enter your password and you're done.

How it's protected:

• Nothing works without signing in: the MCP endpoint answers 401 to anyone without a token.

• The password is compared in constant time; after 10 wrong attempts in 10 minutes, sign-in is blocked for the rest of that window (so someone guessing can lock you out briefly).

• Tokens expire after an hour and are refreshed automatically; authorization codes work once.

• Apps can only register redirect addresses on claude.ai, claude.com or localhost, so a malicious link can't send your login to someone else's site. Add more with --allow-redirect-host.

• If you don't set a password, one is generated and printed when the server starts.

Limits: use a long, unique password and keep the tunnel closed when you're not using it. Sessions are kept in memory, so restarting the server signs you out. Free tunnel addresses usually change on every restart, so you'll need to update the connector URL and --public-url. Sign-in mode is tested with mcp 2.x.

Simpler alternative: secret in the URL

If you'd rather not use a login page, capcut-mcp --http --port 8000 serves the connector at <tunnel address>/<secret>/mcp, where the secret comes from CAPCUT_MCP_SECRET (16+ characters, or one is generated). Anyone who learns the full URL has full access, so sign-in mode is the better choice.

Tools

All times are in seconds. Tools that create segments return a segment_id you can pass to add_transition, add_animation, add_fade and add_keyframe.

Example prompt: "Make a 1080x1920 draft called promo. Put clip1.mp4 and clip2.mp4 back to back (4 s each) with a transition between them, add music.mp3 underneath with a 1 s fade-out, and caption it with captions.srt. Save it."

Caveats

• Close the draft in CapCut before saving over it, and restart CapCut (or re-enter the drafts list) to see new drafts.

• The draft format is proprietary and changes between CapCut versions, and effect/transition/font catalogs come from the pyJianYingDraft library, which is oriented around Jianying (the Chinese edition). Some catalog entries may not exist in CapCut International. Keep backups of drafts you care about.

• Editing existing drafts is not supported yet; the server creates new drafts.

• Draft names are restricted to plain folder names (no path separators), because replace=true deletes the existing folder.

Development

pip install -e ".[dev]"
pytest

CI runs the tests on Linux, macOS and Windows.

License

MIT. Built on pyJianYingDraft; see its repository for its license.