> This is the Markdown version of the Azimo developer docs page "CLI and MCP", for use by an AI assistant.
> - Azimo (https://azimo.ai) is an AI business-video production service: a brief and a few files in, a QA-checked commercial video out. It offers an asynchronous REST API, Python and TypeScript SDKs, the azimo command line and an MCP server.
> - Base URL: https://azimo.ai
> - Auth: every /v1 request sends `Authorization: Bearer <API key>` (create a key at https://azimo.ai/console#account); `X-Project-ID` selects a project, the default project otherwise.
> - This page: https://azimo.ai/en/developers/cli-mcp
> - Prices are not published: contact sales@azimo.ai.

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

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

## Sign in

Create a key at [https://azimo.ai/console](https://azimo.ai/console) under **Account → API Key**, then:

```bash
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:

```bash
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:

```bash
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"
```

| Command | What it does |
| --- | --- |
| `azimo playground` / `azimo types` | Ready-made workflows; structured types and their fields |
| `azimo assets upload FILE...` | Upload material and print the asset ids |
| `azimo plan ...` | Create a plan without starting production |
| `azimo create --plan ID` | Start production from a plan |
| `azimo run ...` | Create a plan, ask you on a terminal, then start (`--yes` skips the question; scripts are never asked) |
| `azimo status ID` / `azimo wait ID` / `azimo list` | Show, wait for, or list videos |
| `azimo download ID --name all` | Save the film, subtitles and cover |
| `azimo resume ID --message "..."` / `--approve-budget` | Answer a `needs_input` video, or approve it to continue |
| `azimo cancel ID` / `azimo balance` | Cancel a video; show your balance |

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

```bash
# 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`.

```json
{
  "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:

```json
{
  "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](https://azimo.ai/en/developers/advanced) and the [API reference](https://azimo.ai/en/developers/api) for more.