Video Studio MCP Server

Video Studio MCP lets AI agents call the cloud AI creation service and local content download tools.

Features

• AI video generation with models such as Sora, Grok, and Veo.

• AI image generation and editing.

• Video content analysis.

• Copywriting/chat helper.

• Douyin/Xiaohongshu download helpers.

• Balance and generation status checks.

• Billing receipts after billed calls: generation tools read the cloud balance endpoint and report the current balance and settlement/refund state.

Related MCP server: douyin-mcp-server

Quick Start

Install dependencies:

pip install -r requirements.txt

Add the server to your MCP config:

{
  "mcpServers": {
    "video-studio": {
      "command": "python",
      "args": ["/path/to/mcp-server/server.py"]
    }
  }
}

Then ask your agent to log in:

Login to video-studio with username xxx and password xxx.

Tools

Every billed tool uses the cloud billing system; MCP never deducts credits locally. For proxy calls, the cloud creates a recoverable reservation, settles it on clear success, and refunds clear terminal failures. For videos, creation is initially a pre-charge and video_status reports the final outcome.

Billing interfaces

The cloud endpoints used by MCP are:

• GET /api/credits/balance: current balance, { "credits_balance": 80 }.

• GET /api/credits/costs: default and model-level pricing rules.

• GET /api/credits/history: auditable credit ledger.

• POST /api/dispatch/request and POST /api/dispatch/report: reservation and settlement for direct-dispatch services such as video analysis.

Generation tools append a 计费回执 section to their normal result. It includes the cloud pricing rule when available, whether the request was settled, pending, or refunded, and a post-call balance snapshot. The balance is a concurrent snapshot; use /api/credits/history for exact attribution when multiple calls run at once.

Example:

生成完成！共 1 张图片:
  1. https://cdn.example/image.png
计费回执；规则费用=20积分；本次调用已由云端结算；当前余额=80积分。

For the complete lifecycle and troubleshooting guidance, see docs/billing.md in this repository and docs/mcp-and-billing.md in the main repository.

Generation Contract

MCP follows the same client contract as frontend, local backend, and future CLI clients:

• Image requests use OpenAI-style fields such as model, prompt, size, n, and images for reference-image generation (up to 9 references).

• Before image generation/editing, MCP reads /api/models/params and validates the selected model's live sizes. Common aliases 1:1, 16:9, 9:16, 3:2, and 2:3 are converted to the configured pixel size; auto is passed through only when the model advertises it. Unsupported values such as 1920x1080 or 4K are rejected locally with the available-size list.

• Local reference images are prepared in memory and never overwrite the source file. Opaque images are compressed as JPEG; images with alpha remain PNG. The MCP caps the prepared image at 7 MiB and 4096 px on the longest edge, keeping it below the cloud's 8 MiB public-reference limit.

• Video requests use OpenAI-style fields such as model, prompt, size, seconds, and input_reference.

• Cloud normalizes those fields into canonical routing params and then applies provider field_mapping.

MCP convenience arguments are converted to the cloud public contract; provider-only fields such as aspect_ratio, image_size, and reference_images are not sent.

Project Structure

mcp-server/
  server.py
  SKILL.md
  requirements.txt
  .env.example
  output/
  downloads/

Testing

Run the offline contract test; it does not call the cloud and does not consume credits:

python test_contract.py

Live integration tests consume credits. Use a dedicated test account and set credentials via environment variables; do not commit passwords:

MCP_TEST_USERNAME='test-user' MCP_TEST_PASSWORD='***' python test_all.py

License

MIT