ShiLiu-MCP by shiliu-ai - MCP Server

ShiLiu MCP Server — Digital Human, Voice Cloning and Video Generation

An MCP server for the ShiLiu API that brings digital human (avatar) creation, voice cloning, and video generation into any MCP‑compatible client (e.g., Claude Desktop, Cline, OpenAI Agents). It exposes a focused set of tools over stdio for managing credits, listing avatars and speakers, creating avatars from image/video URLs, generating videos by text, and polling generation status.

Features:
- Retrieve remaining credits of your account
- List avatars and speakers
- Create avatar from an image URL
- Create avatar from a video URL
- Create video by text using selected avatar and speaker
- Query generation status for avatars, speakers and videos

Requirements

Python >= 3.12
A ShiLiu API Key (SHILIU_API_KEY)
Optional: uv for dependency management

Installation

# Recommended with uv
uv sync

# Or standard pip (editable install if you plan to develop)
pip install -e .

Configuration

Create a .env file in the project root or export environment variables:

# Required
SHILIU_API_KEY=your_api_key_here

# Optional (not strictly required by current server run mode)
MCP_HOST=127.0.0.1
MCP_PORT=8000

Get an API Key at https://shiliu.chat (Contact us).

Run Locally

You can run the server directly or via the installed console script.

# Option 1: run from source
python server.py --api-key YOUR_API_KEY

# Option 2: via entrypoint (available after install)
shiliu-mcp --api-key YOUR_API_KEY

# Option 3: module form (if installed as a package)
python -m shiliu_mcp.server --api-key YOUR_API_KEY

Notes:

The server uses the MCP FastMCP runtime and is intended to be launched by an MCP client (stdio-based).
If --api-key is omitted, ensure SHILIU_API_KEY is set in environment or .env.

Use with MCP Clients

Example for Claude Desktop (adjust paths/commands as needed):

{
  "mcpServers": {
    "shiliu": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "SHILIU_API_KEY": "your_api_key_here"
      }
    }
  }
}

If installed with an executable command (shiliu-mcp):

{
  "mcpServers": {
    "shiliu": {
      "command": "shiliu-mcp",
      "args": [],
      "env": {
        "SHILIU_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Tool	Description	Params
`get_remaining_credits`	Get remaining credits	-
`get_avatar_list`	List available avatars	-
`create_avatar_by_image`	Create avatar by image URL	`image_url`, `title?`
`create_avatar_by_video`	Create avatar by video URL	`video_url`, `title?`
`get_avatar_generation_status`	Query avatar generation status	`avatar_id`
`get_speaker_list`	List available speakers	-
`create_speaker`	Create a new speaker (voice)	`title?`
`get_speaker_generation_status`	Query speaker generation status	`speaker_id`
`create_video_by_text`	Create video by text	`avatar_id`, `speaker_id`, `text`, `title?`
`get_video_generation_status`	Query video generation status	`video_id`

Success responses use code = 0 and include relevant fields such as remaining_credits, avatars, speakers, video_id, progress, status, title, video_url, etc.

Troubleshooting

API Key errors
- Ensure .env is present or SHILIU_API_KEY is exported
Network issues
- Verify connectivity to https://api.16ai.chat
Dependency issues
- Re-install with uv sync or pip install -e .

Development Notes

Code entry point: server.py (CLI parses --api-key, --host, --port, --reload)
Main classes and models are in api_client.py
Packaging metadata is defined in pyproject.toml

Disclaimer

This project interfaces with the ShiLiu API. Please ensure you have the right to use the API and comply with the API provider's terms.