vimax-mcp

MCP server wrapping ViMax for use across multiple CLI clients (Claude Code, Codex, Gemini, Kimi, …).

Implements proposal §1 of ~/projects/ViMax/docs/MCP_PROPOSAL.md.

Status

Steps 1-3 done: 6 tools, stdio + SSE transports, daily-quota gate, launchd agent template, multi-CLI configuration snippets.

Tools

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)

Run

cd ~/projects/vimax-mcp
uv sync

# stdio (default — used when wired into a CLI client)
uv run python -m vimax_mcp.server

# SSE (HTTP, share across all CLI clients on this machine)
uv run python -m vimax_mcp.server --transport sse --port 7801

Wire to Claude Code

stdio (per-CLI subprocess) — ~/.claude/.mcp.json or project .mcp.json:

{
  "mcpServers": {
    "vimax": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/zcdeng/projects/vimax-mcp",
               "python", "-m", "vimax_mcp.server"]
    }
  }
}

SSE (shared instance, recommended for multi-CLI) — run vimax-mcp --transport sse once (e.g. via launchd in step 3), then point each client at it:

{
  "mcpServers": {
    "vimax": {
      "transport": "sse",
      "url": "http://127.0.0.1:7801/sse"
    }
  }
}

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 --transport sse --port 7801 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 -sI http://127.0.0.1:7801/sse | head -1   # → 200 OK
tail -f ~/projects/ViMax/.working_dir/logs/mcp.{out,err}.log

Wire into your CLI clients

Ready-to-copy snippets live in clients/:

Tests

uv run pytest

Smoke tests cover JobRegistry, artifact scanning, FastMCP tool registration, and a full stdio JSON-RPC handshake. They do not invoke ViMax pipelines or consume Veo / MiniMax quota.