[English](README.md) | [中文](README.zh-CN.md)

<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

```bash
# 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:

```bash
# 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.

```bash
# 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):

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

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

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