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 "Install 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-mcpgenerate 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.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that working_dir is preserved, which is a useful side effect. However, it omits details like required permissions, irreversibility, or whether the cancellation is immediate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. Every word carries meaning. Highly concise and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description adequately covers purpose and key behavioral detail (working_dir preservation). It could be slightly more complete by addressing the parameter format, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema lists a single required parameter (job_id) with no description. The tool description does not explain how to obtain or format job_id. Since schema description coverage is 0%, the description should compensate but does not add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancel') and the resource ('a running or queued job'), with an additional note about working_dir preservation. This distinguishes it from sibling tools like get_job_status (status check) and submit_* (submission).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use (for running or queued jobs) but does not provide explicit guidance on when not to use or mention alternatives. For example, it could advise checking status via get_job_status before canceling, or note that canceling is irreversible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_job_statusB
Get current state, progress, and error list for a submitted job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only lists what is returned (state, progress, error list) without disclosing read-only nature, error handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, front-loaded with action and resource; efficient but could be minimally expanded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simplicity, lacks details on return format or potential states; with no output schema, description should provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description adds no extra meaning for the required job_id parameter (e.g., format, where to obtain it).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves current state, progress, and error list for a submitted job, distinguishing it from sibling tools like cancel_job or submit_*.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage when needing job status, but no explicit guidance on when to use or not use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_quotaA
Today's daily quota usage for chat / image / video providers (UTC day).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description states it returns quota usage but does not disclose whether it's read-only, authentication needs, or any side effects. For a simple read tool, lacking explicit transparency is acceptable but not ideal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Clearly and concisely communicates the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description gives a good idea of what to expect (usage per provider). Could mention if it returns numbers or remaining amounts, but adequate for a simple quota check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, schema coverage 100%. Description adds context by specifying the scope (today's, UTC day) and who it covers (chat/image/video providers), adding meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Exactly states it gets today's daily quota usage for chat/image/video providers in UTC day. The verb 'get' and resource 'quota' are clear, and it distinguishes from sibling tools that handle job submissions and status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is to check quota before submitting jobs, but no explicit when-to-use or alternatives. No mention of when not to use or compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_artifactsB
List files produced by a job. kind ∈ final | frames | intermediate | all.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| kind | No | all |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose behavioral traits such as whether the job must be completed, pagination, order of results, or any side effects. The description only hints at the kind parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with a clear separation of purpose and parameter info. It could be improved with a more structured format, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is insufficient: it does not mention the return format, whether the job must be in a certain state, error handling, or limits on the number of artifacts listed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by enumerating valid kind values ('final | frames | intermediate | all'), but does not explain the job_id parameter beyond its necessity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List files') and the resource ('produced by a job'), and mentions the kind parameter with valid values, distinguishing it from sibling tools like cancel_job or get_job_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or context for the job_id parameter, and no explanation of the different kind options' use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_idea2videoA
Submit an idea-to-video job. Returns immediately with a job_id; poll get_job_status for progress.
| Name | Required | Description | Default |
|---|---|---|---|
| idea | Yes | ||
| user_requirement | No | ||
| style | No | ||
| profile | No | default | |
| job_id | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses the asynchronous nature (returns job_id immediately) and the need to poll for completion. It does not discuss failure modes, idempotency, or auth requirements, but covers the core behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. The most important information (purpose and async behavior) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 undocumented parameters, the description is insufficient. It doesn't specify the response format beyond 'job_id', nor does it explain parameter semantics or constraints (e.g., idea character limit).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 5 parameters (idea, user_requirement, style, profile, job_id). The agent gets no help understanding what each parameter means or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Submit' and the resource 'idea-to-video job', differentiating it from sibling tools like get_job_status and cancel_job. The asynchronous behavior is also made explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context by telling the agent to poll get_job_status for progress, implying a two-step workflow. However, it does not explicitly state when not to use the tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_script2videoC
Submit a script-to-video job. Returns immediately with a job_id; poll get_job_status for progress.
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | ||
| user_requirement | No | ||
| style | No | ||
| profile | No | default | |
| job_id | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only mentions the asynchronous nature (returns immediately, poll for progress) but omits other critical traits like destructiveness, authentication needs, rate limits, or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action ('Submit'), and wastes no words. It is efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 undocumented parameters, no output schema, no annotations), the description fails to provide sufficient context. It does not explain return values beyond job_id, parameter roles, error handling, or lifecycle details, leaving large gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters with 0% coverage (no descriptions), and the tool description does not explain any parameter meanings or defaults. Only 'script' is implied by the tool name, but parameters like 'user_requirement', 'style', 'profile', and 'job_id' are left completely undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits a script-to-video job and returns a job_id immediately, indicating a clear action. It differentiates from the sibling 'submit_idea2video' by specifying 'script' as input, though it does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case: when you have a script to convert to video. It also advises polling 'get_job_status' for progress. However, it lacks guidance on when not to use this tool or alternatives like 'submit_idea2video', limiting its completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v0.1.0- First observed
cancel_job - First observed
get_job_status - First observed
get_quota - First observed
list_artifacts - First observed
submit_idea2video - First observed
submit_script2video
TDQS
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
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.
Create and manage AI image and video generations through Quriov's fixed public MCP tools.
Create and edit AI videos from chat: plan shots, generate scenes, and export stories and ads.
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.1-
- 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 and image-to-video using Google Veo AI models via the Gemini API.62MIT
- AlicenseAqualityCmaintenanceEnables video generation from text prompts or images using Agnes AI's video models, with async task submission and status polling.227MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ZCDeng/vimax-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server