hoox-mcp 0.1.2

MCP server for Hoox — AI video generation platform

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 / WSL / Git Bash

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   Or, if you prefer:

   brew install uv
   

   Windows (PowerShell)

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

3. Add the following configuration to your claude_desktop_config.json (Claude → Preferences → Developer → Edit Config):

{
  "mcpServers": {
    "Hoox": {
      "command": "uvx",
      "args": ["hoox-mcp"],
      "env": {
        "HOOX_API_KEY": "hx_live_your_key_here"
      }
    }
  }
}

Other MCP clients

For Cursor, Windsurf, or any other compatible client:

pip install hoox-mcp

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 with a professional style"
• "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"

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
list_resource_voices	Simplified voice list optimized for generation

Avatars

Tool	Description
list_avatars	List available avatars with optional filters (gender, tags)
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
list_resource_avatars	Simplified avatar list optimized for generation

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

1. list_resource_voices / list_resource_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

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.