Hoox MCP Server

Official Model Context Protocol (MCP) server for Hoox — the AI video generation platform. This server lets any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) generate videos, manage avatars and voices, and export MP4 files using natural language.

Quickstart with Claude Desktop

1. Get your API key from app.hoox.video → Settings → API Keys. An Enterprise plan is required to access the API.

2. Install uv (Python package manager):

   macOS / Linux

   brew install uv
   

   Windows (PowerShell)

   irm https://astral.sh/uv/install.ps1 | iex
   

   If you run into issues, see the uv installation documentation.

3. Open your claude_desktop_config.json (Claude → Preferences → Developer → Edit Config)
   and add the "mcpServers" block alongside your existing settings:

Before

{
  "preferences": {
    "quickEntryShortcut": "off",
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat"
  }
}

After

{
  "preferences": {
    "quickEntryShortcut": "off",
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat"
  },
  "mcpServers": {
    "Hoox": {
      "command": "uvx",
      "args": ["hoox-mcp@latest"],
      "env": {
        "HOOX_API_KEY": "hx_live_your_key_here"
      }
    }
  }
}

Add the "mcpServers" block to your existing config file — keep your other settings intact.

Other MCP clients

For Cursor, OpenClaw, Claude Code, or any other compatible client:

pip install hoox-mcp

To get the latest tools later, upgrade with pip install -U hoox-mcp and restart your client.

Then add the configuration to your client's MCP configuration file:

{
  "mcpServers": {
    "hoox": {
      "command": "hoox-mcp",
      "env": {
        "HOOX_API_KEY": "hx_live_your_key_here"
      }
    }
  }
}

Your MCP client can now interact with Hoox through the tools listed below.

Example prompts

⚠️ Hoox credits are required to use these tools.

Try for example:

• "Use the Hoox API to generate a 60-second vertical product demo video for our new DTC skincare serum."
• "List the male avatars available in an office setting"
• "Create an avatar from this description: man in a conference room in a suit"
• "Duplicate the video vid_xxx by changing the voice to a male English voice"
• "Generate a 45 second script about our new DTC skincare serum, then start the video generation and export the result as MP4"
• "Generate 4 product images using Flux 2 Pro with a 16:9 ratio"
• "What's the cost to generate a 6-second video with Kling v3 Pro?"

Available tools

Voices

Tool	Description
list_voices	List available voices with optional filters (language, gender, tags)
get_voice	Get details for a voice by ID

Avatars

Tool	Description
list_avatars	List available avatar looks with rich filters (gender, age_range, ethnicity, hair_color, place, action, emotion, accessories, selfie)
get_avatar	Get full details for an avatar and its looks
get_avatar_look	Get details for a specific look
create_avatar	Create a new avatar from a prompt or reference images
edit_avatar	Edit an existing look to create a new variation
get_avatar_status	Check the creation status of an avatar

Asset generation

Tool	Description
list_asset_models	List AI models for image/video generation (filter by type, provider, tag)
get_asset_model	Get full details + input schema for a specific model
get_asset_pricing	Calculate the credit cost before starting a generation
create_folder	Create an asset or video folder to organize the library (type: assets/videos)
list_folders	List existing folders (optionally filter by type) to reuse their IDs
start_asset	Start an image or video generation job (accepts folder_id, parent_media_id)
get_asset_status	Check the status of an asset generation job

Tip — stay organized. When you work on a project or generate a batch of related assets, create a dedicated folder with create_folder (type: "assets") and pass its id as folder_id on each start_asset call. The assistant is primed to suggest this automatically. Reuse an existing folder via list_folders rather than duplicating.

Tip — keep the history. When a generation is derived from an existing asset (edit, animation/image-to-video, upscale, restyle, variation), set start_asset's parent_media_id to the source asset's id — in addition to passing it as the model reference. This links the output to its source in the dashboard's history tree so the full edit chain stays visible (and the new asset inherits the source's folder).

Script

Tool	Description
generate_script	Generate a video narration script from a prompt

Video generation

Tool	Description
start_generation	Start an AI video generation job
get_generation_status	Check the status and progress of a generation job

Export

Tool	Description
start_export	Start exporting a generated video to MP4
get_export_status	Check the status of an export job

Video management

Tool	Description
duplicate_video	Duplicate a completed video, optionally changing the voice or avatar

Typical workflow

Video generation

1. list_voices / list_avatars       →  pick a voice & avatar
2. generate_script (optional)       →  get narration text
3. start_generation                 →  get job_id
4. get_generation_status (polling)  →  get video_id
5. start_export                     →  get export job_id
6. get_export_status (polling)      →  get MP4 download URL

Standalone asset generation

1. list_asset_models                →  pick a model
2. get_asset_pricing (optional)     →  confirm credit cost
3. start_asset                      →  get asset_ids
4. get_asset_status (polling)       →  get output URL

Project / batch (recommended for several related assets)

1. list_folders                     →  reuse an existing folder, or
2. create_folder (type="assets")    →  get folder_id for the project
3. start_asset (folder_id=...)      →  repeat per asset, all grouped
4. get_asset_status (polling)       →  get output URLs

Configuration

Environment variable	Required	Default	Description
HOOX_API_KEY	Yes	—	Your Hoox API key (hx_live_...)

Troubleshooting

"HOOX_API_KEY is required"

Make sure the HOOX_API_KEY environment variable is set in your MCP client configuration. The key must start with hx_live_ or hx_.

Error plan_required (403)

Your Hoox account must have an Enterprise plan to use the API. Upgrade at app.hoox.video.

Error insufficient_credits (402)

Your workspace has run out of credits. Top up from the Hoox dashboard under Settings → Billing.

Error rate_limit_exceeded (429)

The API allows 100 requests per minute on the Enterprise plan. Wait a bit before trying again.

Tool not showing up in Claude Desktop / Cursor

1. Check that hoox-mcp is installed: pip install hoox-mcp or uvx hoox-mcp --help
2. Restart your MCP client after updating the configuration
3. Check your client's logs for connection errors

Claude Desktop logs are located at:

• macOS: ~/Library/Logs/Claude/mcp-server-hoox.log
• Windows: %APPDATA%\\Claude\\logs\\mcp-server-hoox.log

Generation stuck in "processing"

Video generation can take between 1 and 5 minutes depending on duration and options. Use get_generation_status to monitor progress. If the job is stuck for more than 10 minutes, it may have failed — check the error field in the status response.

License

This project is licensed under the MIT License. See LICENSE for details.