Uthana MCP

Local MCP server for Uthana: generate motion from text or video, create characters from prompts, images, or rigged files, trim, loop, and stitch motions, and export retargeted animation.

The host supplies the reasoning model. This server uses the shared Uthana Python client and speaks stdio. It registers 24 tools and the uthana://workflow resource.

📖 API documentation · First animation

Install

Download and run the installer for your platform:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Uthana/uthana-mcp/main/install.sh -o install.sh
sh install.sh

Windows (PowerShell)

Invoke-WebRequest https://raw.githubusercontent.com/Uthana/uthana-mcp/main/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

The installer checks for uv, installs it if needed, and installs the MCP with Python 3.12. No existing Python installation is required. It prints the server command for your host configuration. Create an API key in your Uthana account settings and paste its value into UTHANA_API_KEY below.

See the installation guide for manual installation, environment settings, and tool timeouts.

Connect

Use the absolute server command printed by the installer. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "uthana": {
      "command": "/absolute/path/to/uthana-mcp",
      "args": [],
      "env": {
        "UTHANA_API_KEY": "your-api-key",
        "UTHANA_MCP_INPUT_DIR": "/absolute/path/to/selected-inputs"
      }
    }
  }
}

Cursor (.cursor/mcp.json) uses the same mcpServers object.

Codex (~/.codex/config.toml):

[mcp_servers.uthana]
command = "/absolute/path/to/uthana-mcp"
args = []

[mcp_servers.uthana.env]
UTHANA_API_KEY = "your-api-key"
UTHANA_MCP_INPUT_DIR = "/absolute/path/to/selected-inputs"

Install and connect has Windows path examples and host timeout settings.

Restart your host, then ask it to read Uthana’s workflow, check account access, and estimate a motion before generating it. Production generation spends your account’s credits. Continue with the first-animation walkthrough for upload, generation, and export.

Tools

UthanaAPI.generate_v1 is a Python adapter method for V1 generation. It is not a separate MCP tool.

Join two motions

Call the stitch tool with the following arguments, or ask your host to stitch the selected motions. Replace the character and motion IDs with your own.

Simple join

Join two motions with automatic positioning. The server handles sampling and alignment.

{
  "request_id": "stitch-basic",
  "character_id": "CHARACTER_ID",
  "steps": [
    {
      "type": "motion",
      "motion_id": "FIRST_MOTION_ID"
    },
    {
      "type": "transition",
      "duration_seconds": 1.0
    },
    {
      "type": "motion",
      "motion_id": "SECOND_MOTION_ID"
    }
  ]
}

Join with ranges and positioning

Select source intervals and place the second motion one meter forward and half a meter right of the first motion’s ending pelvis, turned 45 degrees right. Placement is relative to the first motion’s ending facing.

{
  "request_id": "stitch-positioned",
  "character_id": "CHARACTER_ID",
  "steps": [
    {
      "type": "motion",
      "motion_id": "FIRST_MOTION_ID",
      "range": {
        "start_frame": 12,
        "end_frame": 60
      }
    },
    {
      "type": "transition",
      "duration_seconds": 1.5
    },
    {
      "type": "motion",
      "motion_id": "SECOND_MOTION_ID",
      "range": {
        "start_seconds": 0.5,
        "end_seconds": 3.0
      },
      "placement": {
        "forward_m": 1.0,
        "right_m": 0.5,
        "turn_degrees": 45.0
      }
    }
  ]
}

Choose ranges that fit your source motions and leave the required transition context. Frame indices use each source’s native FPS; do not mix frames and seconds within one range. Inspect resolved_steps and review playback before accepting the result.

Each example makes a separate mutation. Use a distinct request ID for different arguments; recover an uncertain request before retrying. See stitching for the full contract.

Documentation

• Workflow and recovery
• API coverage and limits
• Stitching steps and positioning
• Install and connect
• First animation and export
• Operational checks
• Contributing
• Public API documentation

Develop from source

uv sync --locked
uv run --locked bash ./test.sh

Licensed under Apache-2.0.