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.

Version and updates

The MCP server has its own semantic version (MCP_VERSION) and sends it to the cloud as X-MCP-Version on every request. The cloud exposes the read-only GET /api/mcp/version policy endpoint. Cloud responses also carry update headers, so billed MCP results can include a version reminder. Run check_mcp_update() to compare the installed version with the latest/minimum versions and get release notes.

The recommended update is:

git pull origin master
pip install -r requirements.txt --upgrade

Restart the MCP process (or open a new agent session) after updating. The MCP server intentionally does not overwrite its own running process or credentials.

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 optional images for reference-image generation (up to 9 references). The single public endpoint /api/v1/images/generations selects text-to-image when no images are supplied and the image-input workflow when images are supplied.

• Before image generation, MCP validates the generic size contract: auto or any 宽x高 pixel size with both dimensions divisible by 16 and no larger than 4096x4096. Common ratio aliases are convenience inputs; they are converted to pixel values. The model preset list is informational, not an allowlist.

• 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