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: TensorsLab MCP Server

Tools

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

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  # 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/:

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.