CLI and MCP

Make videos from your terminal with the azimo command, or connect Azimo over MCP so an AI assistant such as Claude or Cursor can upload, plan, produce and download for you.

Install#

The command line, the MCP server and the Python SDK ship in one Python package, vidgen-sdk. It needs Python 3.9 or later and depends only on requests.

The package is not on PyPI yet. During the beta, ask sales@azimo.ai for it, then install the folder you receive with pipx or pip:

pipx install ./vidgen-sdk      # or: pip install ./vidgen-sdk
azimo version

Sign in#

Create a key at https://azimo.ai/console under Account → API Key, then:

azimo login                           # type the key (hidden); saved only if it works
echo "$AZIMO_API_KEY" | azimo login   # or pipe it in
azimo whoami                          # shows your role, organization and project

The key is stored in ~/.config/azimo/config.json, readable only by you. You can skip login and set AZIMO_API_KEY instead. To work in another project, pass --project or set AZIMO_PROJECT.

The commands you will use#

A whole film, start to finish:

azimo playground                        # see the ready-made workflows
azimo assets upload brief.pdf logo.png  # upload material, get asset ids
azimo plan --prompt "A 30-second film for food-industry buyers on why our cold-chain delivery is more reliable" \
  --duration 30 --ratio 9:16 --subtitles --asset 3f2a9c1b7d6e4a58
azimo create --plan 53f755f4a1b24c0e     # start production (uses your balance)
azimo wait 188f86a5c3d94e21              # wait until it finishes
azimo download 188f86a5c3d94e21 --name all --dir ./out

For a structured type, use --type with one --field per input. azimo types lists the field names:

azimo plan --type product --duration 30 \
  --field product_name="Pliva Fold Kettle" --field audience_role="Business travellers" \
  --field usage_scenario="A hotel room late at night" --field main_benefits="Folds flat; two cups; no spills" \
  --field demonstration="Unfold, boil, pour, fold" --field evidence="Spec sheet from the client" \
  --field purchase_action="Search for it in the official store"

Useful azimo plan flags: --prompt or --prompt-file, --workflow, --type, --field, --duration (seconds), --ratio (16:9, 9:16 or 1:1), --asset (repeatable), --subtitles and --no-music.

Every command accepts --json for machine-readable output. Exit codes: 0 success, 1 error, 2 usage error, 3 wait ended without a finished film, 4 missing or invalid key.

Watch out: every azimo create run starts a new production, so running it twice on the same plan makes two videos.

Connect an AI assistant (MCP)#

There are two ways to connect, with exactly the same tools:

• Local (recommended): azimo mcp runs on your computer and can upload files straight from your disk. Install the package above first.
• Remote: https://azimo.ai/mcp, nothing to install; authenticate with the header Authorization: Bearer <API key>. It cannot read files on your computer: the assistant sends file contents instead, up to 20 MB per file.

Claude Code#

# Local; you can drop --env if you have run azimo login
claude mcp add --env AZIMO_API_KEY="$AZIMO_API_KEY" azimo -- azimo mcp

# Remote
claude mcp add --transport http azimo https://azimo.ai/mcp --header "Authorization: Bearer $AZIMO_API_KEY"

Claude Desktop#

Use the local server. Add this to claude_desktop_config.json; if azimo is not found, set command to the full path printed by which azimo.

{
  "mcpServers": {
    "azimo": {
      "command": "azimo",
      "args": ["mcp"],
      "env": {"AZIMO_API_KEY": "your-api-key"}
    }
  }
}

Cursor#

Edit ~/.cursor/mcp.json. The local setup is the same as for Claude Desktop. For the remote server:

{
  "mcpServers": {
    "azimo": {
      "url": "https://azimo.ai/mcp",
      "headers": {"Authorization": "Bearer ${env:AZIMO_API_KEY}"}
    }
  }
}

Then just ask: "Make a 30-second product video for the Pliva Fold Kettle."

What the assistant can and cannot do#

It can list workflows and the fields each type needs, upload files you point it to, create plans, start production once you agree, follow progress, and hand you the download links. When a video needs input it relays the question, and it can approve a paused video after you say yes. It can also show your balance and cancel videos.

It must show you the plan first. Production can only start from a plan, and the tools tell the assistant to show you the plan (workflow, length, format) and wait for your explicit yes. Starting production, approving extra spending and cancelling are marked as actions that need confirmation, so most clients ask you before running them. Repeating the start call on the same plan returns the same video.

It cannot see or quote prices (contact sales@azimo.ai for pricing) or get around your balance and limits. The local server refuses hidden files and folders such as ~/.ssh, and the remote server cannot read your computer's files at all.

Stay safe#

• Give each client its own key, so a leak means revoking just that one.
• If the assistant only needs to check progress, give it a viewer key: it cannot create plans or start production.
• Never paste a key into a chat; keep it in an environment variable or the config file.

Troubleshooting#

• Exit code 4 or HTTP 401: the key is missing, wrong or revoked. Run azimo login again.
• 403 read-only key: you are using a viewer key; switch to editor or owner.
• 402: not enough balance, or a spending limit was reached.
• The plan is needs_input: fix what requirements lists; for example unsupported_duration means the length is outside the workflow's range.
• The MCP client says the server failed to start: run azimo mcp in a terminal and read the error on stderr.

See Advanced usage and the API reference for more.