vimax-mcp
The vimax-mcp server provides an interface to an AI-powered video generation pipeline, allowing you to submit, monitor, and manage video creation jobs:
Submit Idea to Video (
submit_idea2video): Initiate a video generation job from a text prompt/idea, with optional style, profile, and user requirements. Returns ajob_idfor async tracking.Submit Script to Video (
submit_script2video): Start a video generation job from a screenplay/script with the same optional parameters. Also returns ajob_idimmediately.Get Job Status (
get_job_status): Poll the current state, progress, and any errors for a specific job using itsjob_id.List Artifacts (
list_artifacts): Enumerate output files produced by a job, filterable by kind:final,frames,intermediate, orall.Cancel Job (
cancel_job): Terminate a running or queued job while preserving its working directory for inspection.Get Quota (
get_quota): View daily usage and limits across chat, image, and video providers (resets at midnight UTC).Health Check: Verify the liveness and operational status of the daemon.
Leverages Google AI APIs (e.g., Veo) for video generation, controlled via the server's tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vimax-mcp generate a video from this screenplay about space exploration"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vimax-mcp
Daemon + CLI wrapping ViMax for use across multiple AI coding agents (Claude Code, Codex, Gemini, Kimi, …).
Primary path: REST API + vimax CLI authorized via Bash(vimax:*).
MCP transport still ships in the same process for hosts that can only speak MCP — see Advanced: MCP transport.
Why REST + CLI
docs/plans/2026-05-19-001-feat-api-cli-transport-plan.md walks through the migration. Short version:
ViMax jobs are coarse (one
submitreturns ajob_id, then poll). MCP's typed-schema strength is wasted on a "submit and poll" surface.An always-on MCP server prepays ~80–400 tokens of schema per agent session for a tool used <1000 times in local history. That's a permanent token tax.
A
vimaxshell command can be reproduced from any terminal, debugged withcurl, and shared across hosts that don't speak MCP.
Background: docs/MCP_PROPOSAL.md (the original MCP design + POC data) and ~/projects/html-anything/docs/solutions/agent-tool-architecture-api-mcp-cli.md (the API+CLI empirical case study this repo follows).
Related MCP server: Sisif AI MCP Server
Tools
Tool | Purpose |
| Kick off idea → video. Returns |
| Same, but starting from a screenplay. |
| State + progress (inferred from working_dir contents) + errors. |
| List job output files. |
| Stop a running or queued job; working_dir preserved. |
| Today's used / limit per provider (UTC day, resets at midnight UTC). |
| Daemon liveness probe. |
Global flags: --server URL (default http://127.0.0.1:7801), --json for structured output, --timeout seconds.
REST endpoints under http://127.0.0.1:7801/api/v1/ mirror these one-to-one (e.g. POST /jobs/idea2video, GET /jobs/{job_id}, GET /quota, GET /health). The CLI is a thin wrapper — curl or httpie can drive the same flows.
Requirements
Python 3.12+,
uvA ViMax checkout at
$VIMAX_HOME(defaults to~/projects/ViMax)ViMax already wired with
MINIMAX_API_KEYandGOOGLE_API_KEYenv vars (see ViMax fork's.env.example)
Quickstart
cd ~/projects/vimax-mcp
uv sync
# 1. Run the daemon (REST + MCP SSE on 127.0.0.1:7801).
uv run python -m vimax_mcp.server
# In production, install as a launchd agent — see "Deploy as a launchd agent".
# 2. Install the vimax CLI symlink into ~/.local/bin.
./scripts/install-cli.sh
# Make sure ~/.local/bin is on PATH (the script warns if it isn't).
# 3. Smoke test.
vimax health
vimax quotaOnce the daemon is up and vimax is on PATH, the rest is shell:
vimax submit-idea --idea "a cat on a roof at sunset" --style "Studio Ghibli, warm"
# → job_id: 01HZ8XKQM2A...
vimax status 01HZ8XKQM2A
vimax artifacts 01HZ8XKQM2A --kind finalWire into agents — Claude Code
Drop clients/claude-code.settings.json into ~/.claude/settings.json (or your project's .claude/settings.json):
{
"permissions": {
"allow": ["Bash(vimax:*)"]
}
}That's it. The agent can call any vimax ... subcommand without prompting. Output is human-readable by default; agents typically prefer vimax --json status <id> for structured parsing.
Wire into agents — Codex
If your Codex build supports running shell commands, allow vimax and skip the MCP block entirely.
If you need MCP fallback, append clients/codex.config.toml (or the inline snippet below) to ~/.codex/config.toml:
[mcp_servers.vimax]
command = "uv"
args = [
"run",
"--directory",
"/Users/zcdeng/projects/vimax-mcp",
"python",
"-m",
"vimax_mcp.server",
"--transport",
"stdio",
]Stdio bridging spins up a fresh process per Codex session, so the daemon-side quota / job registry is not shared. Use it for ad-hoc debugging, not concurrent multi-client work.
Wire into agents — Gemini, Kimi, etc.
These tend to inherit Claude Code or Codex config via symlinks. Whichever host shape they wrap, the recommendation is the same: prefer Bash(vimax:*) over MCP.
Environment
Var | Default | Purpose |
|
| Path to ViMax checkout (added to |
|
| Per-job output root |
|
| Persisted daily-quota counter |
|
|
|
|
| HTTP bind host |
|
| HTTP bind port |
|
| Daemon log level |
|
| CLI default daemon URL |
|
| CLI request timeout (seconds) |
|
| Where |
| — | Forwarded to ViMax chat model |
| — | Forwarded to ViMax image/video generators |
Deploy as a launchd agent (recommended on macOS)
./scripts/install-launchd.sh # install or refresh
./scripts/install-launchd.sh status # show launchctl print + log tails
./scripts/install-launchd.sh remove # uninstallThe template at launchd/com.zcdeng.vimax-mcp.plist is rendered into
~/Library/LaunchAgents/com.zcdeng.vimax-mcp.plist with your $HOME
and absolute uv path substituted. The agent runs vimax-mcp in
composite mode (REST at /api/v1 + MCP SSE at /mcp/sse) and
restarts on crash.
Secrets are not stored in the plist. The server loads
$VIMAX_HOME/.env on boot (see vimax_mcp/dotenv.py).
Verify:
curl -s http://127.0.0.1:7801/api/v1/health # → {"status":"ok",...}
vimax health
vimax quota
tail -f ~/projects/ViMax/.working_dir/logs/mcp.{out,err}.logAdvanced: MCP transport
The daemon still exposes MCP over SSE at http://127.0.0.1:7801/mcp/sse
and over stdio (run with --transport stdio). Use these when:
An agent host can only speak MCP and can't shell out (rare).
You want to compare behavior between transports for debugging.
You're migrating from a pre-U2 deployment and need a temporary bridge.
Client templates live in clients/:
File | Where to drop it | When to use |
|
| Recommended — Bash permission for |
|
| Opt-in MCP SSE for hosts that need it |
| append to | MCP stdio fallback for older Codex |
If you were on a pre-U2 deployment whose .mcp.json pointed at
http://127.0.0.1:7801/sse, update the URL to
http://127.0.0.1:7801/mcp/sse — the composite server moved MCP under
a /mcp prefix so REST can own the root.
Tests
uv run pytestSmoke tests cover JobRegistry, quota tracker, artifact scanning, REST handlers, composite-server boot, the CLI parser + output formatter, the shell wrapper + install script, FastMCP tool registration, SSE boot, and a full stdio JSON-RPC handshake. They do not invoke ViMax pipelines or consume Veo / MiniMax quota.
Available Tools
6 toolscancel_jobA
Cancel a running or queued job. Working_dir is preserved for inspection.
Inputs: job_id (required).
get_job_statusB
Get current state, progress, and error list for a submitted job.
Inputs: job_id (required).
get_quotaA
Today's daily quota usage for chat / image / video providers (UTC day).
Inputs: no named parameters.
list_artifactsB
List files produced by a job. kind ∈ final | frames | intermediate | all.
Inputs: job_id (required), kind.
submit_idea2videoA
Submit an idea-to-video job. Returns immediately with a job_id; poll get_job_status for progress.
Inputs: idea (required), user_requirement, style, profile, +1 more.
submit_script2videoC
Submit a script-to-video job. Returns immediately with a job_id; poll get_job_status for progress.
Inputs: script (required), user_requirement, style, profile, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct purpose: submitting jobs (two types), canceling, status polling, artifact listing, and quota checking. No overlap or ambiguity.
All tools use lowercase with underscores and follow a verb_noun pattern (e.g., cancel_job, get_job_status). Minor inconsistency: 'submit_idea2video' uses '2' instead of 'to', but otherwise consistent.
6 tools is a well-scoped set for a video generation job server, covering submission, monitoring, cancellation, output retrieval, and quota checking without being overwhelming.
Core lifecycle is covered (submit, cancel, status, artifacts), but missing a way to list all jobs or query by criteria, which may require external tracking of job_ids.
Maintenance
Related MCP Connectors
VIDIA AI video production: get quotes, start videos, track progress and download results
Make short narrated videos from a prompt or a script: estimate the cost, create, track and download.
Create and manage cinematic AI video renders through the Future Video Studio Agent API.
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude to generate AI videos using ViewMax Studio's video generation tools, including prompt and script creation, smart model selection, cost preview, and task status tracking.2-
- AlicenseNot gradedqualityDmaintenanceEnables AI video generation from text prompts, status monitoring, and video management through the Sisif AI Video API.1MIT
- AlicenseAqualityDmaintenanceEnables video generation from text prompts or images using Agnes AI's video models, with async task submission and status polling.21MIT
- FlicenseNot gradedqualityDmaintenanceEnables video generation through ComfyUI workflows, providing tools to list workflows, create and manage video jobs, upload assets, and retrieve results.-