Skip to main content
Glama

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 submit returns a job_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 vimax shell command can be reproduced from any terminal, debugged with curl, 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

vimax submit-idea --idea ...

Kick off idea → video. Returns job_id immediately. Rejects with quota_exhausted if today's video budget is gone.

vimax submit-script --script ...

Same, but starting from a screenplay. @path/to/file loads from disk.

vimax status <job_id>

State + progress (inferred from working_dir contents) + errors.

vimax artifacts <job_id> --kind final|frames|intermediate|all

List job output files.

vimax cancel <job_id>

Stop a running or queued job; working_dir preserved.

vimax quota

Today's used / limit per provider (UTC day, resets at midnight UTC).

vimax health

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+, uv

  • A ViMax checkout at $VIMAX_HOME (defaults to ~/projects/ViMax)

  • ViMax already wired with MINIMAX_API_KEY and GOOGLE_API_KEY env 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 quota

Once 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 final

Wire 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

VIMAX_HOME

~/projects/ViMax

Path to ViMax checkout (added to sys.path at first job)

VIMAX_JOBS_DIR

$VIMAX_HOME/.working_dir/jobs

Per-job output root

VIMAX_QUOTA_FILE

$VIMAX_HOME/.working_dir/quota.json

Persisted daily-quota counter

VIMAX_MCP_TRANSPORT

both

stdio (MCP only), http (REST only), or both (default)

VIMAX_MCP_HOST

127.0.0.1

HTTP bind host

VIMAX_MCP_PORT

7801

HTTP bind port

VIMAX_MCP_LOG

INFO

Daemon log level

VIMAX_SERVER

http://127.0.0.1:7801

CLI default daemon URL

VIMAX_CLI_TIMEOUT

30

CLI request timeout (seconds)

VIMAX_BIN_DIR

$HOME/.local/bin

Where install-cli.sh puts the vimax symlink

MINIMAX_API_KEY

Forwarded to ViMax chat model

GOOGLE_API_KEY

Forwarded to ViMax image/video generators

./scripts/install-launchd.sh         # install or refresh
./scripts/install-launchd.sh status  # show launchctl print + log tails
./scripts/install-launchd.sh remove  # uninstall

The 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}.log

Advanced: 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

clients/claude-code.settings.json

~/.claude/settings.json

Recommended — Bash permission for vimax CLI

clients/claude-code.mcp.json

~/.claude/.mcp.json

Opt-in MCP SSE for hosts that need it

clients/codex.config.toml

append to ~/.codex/config.toml

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 pytest

Smoke 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 tools
cancel_jobA

Cancel a running or queued job. Working_dir is preserved for inspection.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes

TDQS

B3/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters1/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYes
kindNoall

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
ideaYes
user_requirementNo
styleNo
profileNodefault
job_idNo

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
scriptYes
user_requirementNo
styleNo
profileNodefault
job_idNo

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters1/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 6 tool updatesv0.1.0
    • First observedcancel_job
    • First observedget_job_status
    • First observedget_quota
    • First observedlist_artifacts
    • First observedsubmit_idea2video
    • First observedsubmit_script2video

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a distinct purpose: submitting jobs (two types), canceling, status polling, artifact listing, and quota checking. No overlap or ambiguity.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness3/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

Latest Blog Posts

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