Flyworks

Flyworks MCP provides a dedicated server interface to the Flyworks API for fast lipsync video creation. It lets you generate lipsynced videos from audio, text, or avatars with support for both synchronous and asynchronous operation, helping you produce animated digital humans quickly and at scale.

How to use

You connect your MCP client to the Flyworks MCP server to create lipsynced videos. You can drive it with audio or text inputs, and you can create or reuse avatars from images or videos. Choose synchronous mode to wait for the result or asynchronous mode to start a task and check back later. Make sure you have your API token and a valid output directory for generated videos.

To integrate with a MCP client like Claude Desktop, configure the client to run the Flyworks MCP server locally via the provided standard input/output (stdio) flow. This starts the MCP process and forwards your requests to Flyworks. The following configuration is used to launch the MCP server from Claude Desktop:

{
  "mcpServers": {
    "flyworks": {
      "command": "uvx",
      "args": [
        "flyworks-mcp",
        "-y"
      ],
      "env": {
        "FLYWORKS_API_TOKEN": "your_api_token_here",
        "FLYWORKS_API_BASE_URL": "https://hfw-api.hifly.cc/api/v2/hifly",
        "FLYWORKS_MCP_BASE_PATH": "/path/to/your/output/directory"
      }
    }
  }
}

Notes about usage and behavior:

• You can create lipsync videos from an avatar video/image or directly from text with automatic lipsync animation.
• For avatar creation, provide exactly one of avatar_video_url, avatar_image_url, avatar_video_file, or avatar_image_file.
• In async mode, you receive a task_id and can check status later. In sync mode, the tool waits for completion and downloads the video automatically (up to a maximum wait time of 10 minutes).
• Output videos can be saved to a specified path when using sync mode.
• A free trial exists with token-based access, but quotas and watermarks may apply. Contact the provider for full access.

How to install

Prerequisites you need before running the server:
- Python 3.8 or newer
- Dependencies: httpx and mcp[cli]
- Optional tooling for local development: uvx, pygments, pydantic-core (to avoid startup timeouts)

Install and run the MCP server locally using the following steps. Replace placeholder values with your actual tokens and paths.

# 1) Clone the repository
git clone https://github.com/yourusername/flyworks-mcp.git
cd flyworks-mcp

# 2) Install dependencies
pip install httpx "mcp[cli]>=1.6.0"

# If you use uvx
# uvx pip install httpx "mcp[cli]>=1.6.0"

# To avoid startup timeouts, pre-install extras
pip install pygments pydantic-core httpx "mcp[cli]>=1.6.0"

3. Configure your Flyworks API token as an environment variable. You can export it in your shell or put it in a .env file.

# Linux/macOS
export FLYWORKS_API_TOKEN="your_token_here"

# Windows (Command Prompt)
set FLYWORKS_API_TOKEN=your_token_here

# Windows (PowerShell)
$env:FLYWORKS_API_TOKEN="your_token_here"

4. Run the server directly from the source file.

python server.py

If you encounter an ENOENT error for uvx, confirm its absolute path and update the command accordingly.

which uvx

Notes and tips

• The system supports both asynchronous and synchronous operation modes. In sync mode, you can specify an output path to save the finished video.

• Avatar creation via videos typically yields higher quality but may take longer than image-based avatar creation.

• For quick testing, you can create an avatar from an image. This is faster but might deliver lower fidelity than a video-based avatar.

Tool references

Create Lipsync Video by Audio: Generates a lipsynced video from an avatar and an audio input. Supports async and sync modes.

Create Lipsync Video by Text: Generates audio from text and animates the avatar to speak it. Supports async and sync modes.

Check Task Status: Retrieve the status and result of an asynchronous lipsync task using the provided task_id.

Security and tokens

Protect your API token. Do not commit it to public repositories. Use environment variables or a secure secret manager to supply FLYWORKS_API_TOKEN to the MCP server.

Available tools

create_lipsync_video_by_audio

Create a lipsync video by providing an avatar and an audio source. Supports synchronous or asynchronous processing and can derive the avatar from an image/video.

create_lipsync_video_by_text

Create a lipsync video by providing text input. Generates speech using a specified voice and animates the avatar accordingly. Supports async and sync modes.

check_task_status

Check the status and results of an asynchronous lipsync task using the returned task_id.