asimovbox

Command-line tool and MCP server for the AsimovBox video studio. Generate Explainer and Motion Brief videos programmatically with the same account and credit billing as the web studio.

Install

pip install --upgrade asimovbox

Authenticate

Generate a personal API key at asimovbox.com → Account → API access, then:

asimovbox login --token asb_xxxxxxxx
# or set ASIMOVBOX_API_TOKEN / ASIMOVBOX_API_URL in your environment

CLI

asimovbox options                      # current types, tiers, modes, ratios
asimovbox styles                       # visual style templates
asimovbox voices                       # narration voices

# one-shot: create → storyline → render → wait → download
asimovbox make "How DNS works, for beginners" \
  --duration 60 --type explainer --tier premium --wait -o dns.mp4

# or step by step
asimovbox create "How TLS works" --type explainer              # -> {id}
asimovbox storyline <id> --wait        # draft script + scenes
asimovbox render <id>                  # charges credits, starts render
asimovbox status <id>                  # poll status; download_url when ready
asimovbox download <id> -o out.mp4

Rendering charges credits against your account, exactly like the web studio.

MCP server

The package installs an asimovbox-mcp stdio server.

Codex

codex mcp add asimovbox \
  --env ASIMOVBOX_API_URL=https://asimovbox.com \
  --env ASIMOVBOX_API_TOKEN=asb_xxxxxxxx \
  -- asimovbox-mcp

Claude Desktop or Cursor

Add this to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "asimovbox": {
      "command": "asimovbox-mcp",
      "env": {
        "ASIMOVBOX_API_URL": "https://asimovbox.com",
        "ASIMOVBOX_API_TOKEN": "asb_xxxxxxxx"
      }
    }
  }
}

VS Code

Save this as .vscode/mcp.json:

{
  "servers": {
    "asimovbox": {
      "type": "stdio",
      "command": "asimovbox-mcp",
      "env": {
        "ASIMOVBOX_API_URL": "https://asimovbox.com",
        "ASIMOVBOX_API_TOKEN": "asb_xxxxxxxx"
      }
    }
  }
}

Tools: list_video_options, list_style_templates, list_voices, create_video, generate_storyline, update_video, render_video, get_video, download_video, list_music, and finalize_video.

Private ElevenLabs voices

For a private or cloned ElevenLabs voice, configure its API key in the stdio MCP environment and pass the voice ID to render_video:

{
  "mcpServers": {
    "asimovbox": {
      "command": "asimovbox-mcp",
      "env": {
        "ASIMOVBOX_API_URL": "https://asimovbox.com",
        "ASIMOVBOX_API_TOKEN": "asb_xxxxxxxx",
        "ASIMOVBOX_ELEVENLABS_API_KEY": "your-elevenlabs-key"
      }
    }
  }
}

The render tool also accepts elevenlabs_api_key directly, but the environment variable is recommended so the secret does not need to be pasted into a model conversation. AsimovBox validates access to the requested voice_id before billing and uses the key only for that render.

Configuration precedence

explicit flags → environment (ASIMOVBOX_API_URL, ASIMOVBOX_API_TOKEN) → ~/.config/asimovbox/config.json → defaults (https://asimovbox.com).