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

Avatars

Asset generation

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

Video generation

Export

Video management

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

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.