ShiLiu MCP Server

English | 中文

<p align="center"> <img src="shiliu_logo.png" alt="ShiLiu Digital Human" width="320" /> </p>

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.