@infimind/video-mcp-cli

MCP Server for Sora AI Video Generator - Access video generation features through Claude Desktop.

What is MCP?

MCP (Model Context Protocol) is an open protocol that enables Claude Desktop to securely connect to external data sources and tools. This MCP server allows you to interact with the Sora AI Video Generator API directly from Claude Desktop.

Installation

Via npm (Recommended)

npm install -g @infimind/video-mcp-cli

Via npx (No installation required)

{
  "mcpServers": {
    "sora-video-generator": {
      "command": "npx",
      "args": ["-y", "@infimind/video-mcp-cli"],
      "env": {
        "SORA_MCP_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Configuration

1. Get Your API Token

1. Log in to your Sora AI Video Generator account
2. Navigate to "API Tokens" in the sidebar
3. Click "New Token" and give it a name
4. Copy the generated token (it will only be shown once!)

2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sora-video-generator": {
      "command": "sora-mcp",
      "env": {
        "SORA_MCP_TOKEN": "YOUR_TOKEN_HERE",
        "SORA_API_URL": "https://your-api-domain.com/api"
      }
    }
  }
}

Environment Variables

• SORA_MCP_TOKEN (recommended): Your MCP API token. This avoids exposing the token in process arguments.
• SORA_API_URL (optional): Your API base URL. Defaults to http://localhost:3000/api

--token=YOUR_TOKEN remains supported for backward compatibility. --token-env=CUSTOM_ENV_NAME can be used when the token is stored in a different environment variable.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

Available Tools

get_user_info

Get information about the authenticated user.

Example usage in Claude:

Get my user information for the video generator

create_video_task

Create a video generation task.

Supported engines:

• S2: 极睿Sa专业版
• S5: 极睿Sd专业版 (VIP only)
• S6: 极睿Ha专业版 (VIP only)

Parameter applicability:

| Parameter | S2 极睿Sa专业版 | S5 极睿Sd专业版 | S6 极睿Ha专业版 | | --- | --- | --- | --- | | sourceImage | Optional single image | Not supported | Standard mode single image | | sourceImages | Not supported | allinone / firstlast images | reference / edit reference images | | sourceVideos | Not supported | allinone reference videos | edit input videos | | sourceAudios | Not supported | allinone reference audio | Not supported | | sourceVideoDurationSeconds | Not supported | dryRun estimate for videos | dryRun estimate for edit video | | sourceAudioDurationSeconds | Not supported | dryRun estimate for audio | Not supported | | taskMode | Not needed | allinone / firstlast | standard / reference / edit | | resolution | Not supported | 720p / 1080p | 720p / 1080p | | ratio | Not supported | Not supported | reference or text-to-video standard mode | | generateAudio | Not supported | Optional | Not supported | | webSearchEnabled | Not supported | Optional | Not supported | | dryRun | Optional preflight | Optional preflight | Optional preflight |

Local file paths and public URLs are both supported.

Video inputs support MP4/MOV. Audio inputs support MP3/WAV. The server validates media duration, size, count, resolution, and URL safety before estimating credits or creating tasks.

Media limits:

• Local video files: MP4/MOV, up to 50MB each, 2-15 seconds.
• Local audio files: MP3/WAV, up to 15MB each, 2-15 seconds.
• S5 allinone: up to 9 images, 3 videos, and 3 audio files.
• S5 firstlast: up to 2 images; the first frame is required.
• S6 reference: up to 9 images.
• S6 edit: up to 1 video and 5 images.

URL safety rules:

• Only http and https URLs are accepted.
• localhost, 127.0.0.1, private network addresses, reserved IP ranges, and file: URLs are rejected.
• Redirect targets are revalidated.
• Remote files that are too large, not media, or cannot be read safely are rejected.

Use dryRun: true to validate parameters, VIP access, media rules, and estimated credits without creating a task or deducting credits. If a dry run includes video or audio, add sourceVideoDurationSeconds / sourceAudioDurationSeconds to get an estimated credit result. If these duration fields are omitted, dry run can still pass, but the result may not include estimatedCredits.

Dry run before creating a task

{
  "prompt": "@图片1 作为角色参考，生成自然的走秀镜头",
  "route": "S6",
  "taskMode": "reference",
  "sourceImages": ["/path/to/character.jpg"],
  "seconds": 10,
  "ratio": "9:16",
  "resolution": "720p",
  "dryRun": true
}

极睿Sa专业版 - 标准生成

S2 uses sourceImage, seconds, and size; do not pass taskMode or resolution.

{
  "prompt": "一个高质感的产品展示视频，柔和布光，镜头缓慢推进",
  "route": "S2",
  "sourceImage": "/path/to/product.jpg",
  "seconds": 10,
  "size": "720x1280",
  "language": "zh-CN",
  "count": 1,
  "dryRun": true
}

极睿Sd专业版 - 全能参考

{
  "prompt": "根据参考素材生成一个高质感产品展示视频",
  "route": "S5",
  "taskMode": "allinone",
  "sourceImages": ["/path/to/reference.jpg"],
  "sourceVideos": ["/path/to/reference.mp4"],
  "sourceAudios": ["/path/to/music.mp3"],
  "sourceVideoDurationSeconds": [5],
  "sourceAudioDurationSeconds": [5],
  "seconds": 10,
  "size": "720x1280",
  "resolution": "720p",
  "generateAudio": true,
  "webSearchEnabled": false,
  "dryRun": true
}

极睿Sd专业版 - 首尾帧

{
  "prompt": "从首帧自然过渡到尾帧，保持产品主体一致",
  "route": "S5",
  "taskMode": "firstlast",
  "sourceImages": ["/path/to/first-frame.jpg", "/path/to/end-frame.jpg"],
  "seconds": 5,
  "size": "1280x720",
  "resolution": "720p",
  "dryRun": true
}

极睿Ha专业版 - 标准模式

Text-to-video:

{
  "prompt": "一段电影感城市夜景镜头，雨后街道反光，霓虹灯闪烁",
  "route": "S6",
  "taskMode": "standard",
  "seconds": 5,
  "size": "1280x720",
  "ratio": "16:9",
  "resolution": "720p",
  "dryRun": true
}

Image-to-video:

{
  "prompt": "让参考图中的商品在干净摄影棚中缓慢旋转展示",
  "route": "S6",
  "taskMode": "standard",
  "sourceImage": "/path/to/product.jpg",
  "seconds": 5,
  "size": "720x1280",
  "resolution": "720p",
  "dryRun": true
}

极睿Ha专业版 - 图片参考

{
  "prompt": "@图片1 和 @图片2 作为角色参考，生成自然的走秀镜头",
  "route": "S6",
  "taskMode": "reference",
  "sourceImages": ["/path/to/character-1.jpg", "/path/to/character-2.jpg"],
  "seconds": 10,
  "size": "720x1280",
  "ratio": "9:16",
  "resolution": "720p",
  "dryRun": true
}

极睿Ha专业版 - 视频编辑

{
  "prompt": "增强视频的电影感光影，保持人物和商品一致",
  "route": "S6",
  "taskMode": "edit",
  "sourceVideos": ["/path/to/input.mp4"],
  "sourceImages": ["/path/to/reference.jpg"],
  "sourceVideoDurationSeconds": [5],
  "resolution": "720p",
  "dryRun": true
}

After dry run succeeds and the estimated credits look correct, remove dryRun or set it to false to create the real task. After creating a task, use get_video_status with the returned taskId to query progress and video links.

Development

# Clone the repository
git clone <repository-url>

# Install dependencies
cd mcp-server
npm install

# Build
npm run build

# Run MCP smoke tests
npm run test:smoke

# Run in development mode
SORA_MCP_TOKEN=YOUR_TOKEN node dist/index.js

Local MCP testing

MCP Inspector

cd mcp-server
npm run build
SORA_MCP_TOKEN=YOUR_TOKEN npx @modelcontextprotocol/inspector node dist/index.js

Set SORA_API_URL=http://localhost:3000/api when testing against a local app server.

Claude Desktop with local build

{
  "mcpServers": {
    "sora-video-generator-local": {
      "command": "node",
      "args": ["/absolute/path/to/sora_video_generator/mcp-server/dist/index.js"],
      "env": {
        "SORA_MCP_TOKEN": "YOUR_TOKEN",
        "SORA_API_URL": "http://localhost:3000/api"
      }
    }
  }
}

npx against the published package

{
  "mcpServers": {
    "sora-video-generator": {
      "command": "npx",
      "args": ["-y", "@infimind/video-mcp-cli"],
      "env": {
        "SORA_MCP_TOKEN": "YOUR_TOKEN",
        "SORA_API_URL": "https://your-api-domain.com/api"
      }
    }
  }
}

Troubleshooting

• If a client reports schema mismatch, run npm run build and npm run test:smoke in mcp-server.
• If get_video_status cannot connect, verify SORA_API_URL includes /api, for example http://localhost:3000/api.
• If S5/S6 returns VIP errors, confirm the MCP token belongs to a VIP user.
• If S6 reference/edit prompts contain @图片N, keep the original markers; those modes skip prompt translation to preserve image references.
• If local file inputs fail, use absolute paths and supported media types: jpg/png/webp/gif, mp4/mov, mp3/wav.

Publishing

# Build and verify local dist
npm run build
npm run test:smoke

# Verify the package contents that npm will publish
npm run test:smoke:package

# Publish to npm
npm publish --access public

# Optional after publishing: verify latest through npx
npm run test:smoke:published

Security

• Never share your API token with others
• Store tokens securely and rotate them periodically
• Use environment variables for sensitive configuration
• The token is transmitted over HTTPS in production

License

MIT

Support

For issues and support, please visit: https://github.com/infimind/sora-video-generator