Skip to main content
The official Model Context Protocol server for Hoox. Any MCP-compatible client can generate videos, manage avatars and voices, and export MP4 files using natural language.

​
Quickstart — 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"],
      "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
Then add the following to your client’s MCP configuration file: 
{
  "mcpServers": {
    "hoox": {
      "command": "hoox-mcp",
      "env": {
        "HOOX_API_KEY": "hx_live_your_key_here"
      }
    }
  }
}

​
Example prompts

Hoox credits are required to use the MCP tools.
Use the Hoox API to generate a 60-second vertical product demo video for our new DTC skincare serum.
Export the final video to MP4 and return the download URL.

List the male avatars available with a professional style.
Also list female English voices with a conversational tag.

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,
then export the result as MP4.

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

ToolDescription
list_voicesList available voices with optional filters (language, gender, tags)
get_voiceGet details for a voice by ID
list_resource_voicesSimplified voice list optimized for generation

​
Avatars

ToolDescription
list_avatarsList available avatars with optional filters (gender, tags)
get_avatarGet full details for an avatar and its looks
get_avatar_lookGet details for a specific look
create_avatarCreate a new avatar from a prompt or reference images
edit_avatarEdit an existing look to create a new variation
get_avatar_statusCheck the creation status of an avatar
list_resource_avatarsSimplified avatar list optimized for generation

​
Script

ToolDescription
generate_scriptGenerate a video narration script from a prompt

​
Video generation

ToolDescription
start_generationStart an AI video generation job
get_generation_statusCheck the status and progress of a generation job

​
Export

ToolDescription
start_exportStart exporting a generated video to MP4
get_export_statusCheck the status of an export job

​
Video management

ToolDescription
duplicate_videoDuplicate 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

​
Troubleshooting

Make sure the HOOX_API_KEY environment variable is set in your MCP client configuration. The key must start with hx_live_ or hx_.
Your Hoox account must have an Enterprise plan to use the API. Upgrade at app.hoox.video.
Your workspace has run out of credits. Top up from the Hoox dashboard under Settings → Billing.
The API allows 100 requests per minute on the Enterprise plan. Wait a moment before retrying.
  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:
  • macOS: ~/Library/Logs/Claude/mcp-server-hoox.log
  • Windows: %APPDATA%\Claude\logs\mcp-server-hoox.log
Video generation can take 1–5 minutes depending on duration and options. Use get_generation_status to monitor progress. If the job is stuck for more than 10 minutes, check the error field in the status response.