Metadata-Version: 2.4
Name: hoox-mcp
Version: 0.1.2
Summary: MCP server for Hoox — AI video generation platform
Project-URL: Homepage, https://hoox.video
Project-URL: Documentation, https://docs.hoox.video
Author-email: Hoox <alerts@hoox.video>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,generation,hoox,mcp,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Hoox MCP Server

Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Hoox](https://hoox.video) — 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](https://app.hoox.video). An **Enterprise** plan is required to access the API.
2. **Install `uv` (Python package manager):**

   **macOS / Linux / WSL / Git Bash**
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
   Or, if you prefer:
   ```bash
   brew install uv
   ```

   **Windows (PowerShell)**
   ```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):

```json
{
  "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:

```bash
pip install hoox-mcp
```

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

```json
{
  "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

```text
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](https://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.