Content
# Tencent Video Downloader MCP Server
A server based on the Model Context Protocol (MCP) that enables AI assistants to search, retrieve information, and download Tencent videos.
## Features
- **Video URL Parsing**: Extract title, duration, description, and upload date from Tencent video URLs.
- **Quality Selection**: Retrieve available quality options (1080P, 720P, 480P, etc.).
- **Video Download**: Download videos in specified quality.
- **Format Conversion**: Automatically convert videos to standard MP4 (H.264) format.
- **Progress Tracking**: Real-time download progress feedback.
- **Error Handling**: Structured error messages with actionable suggestions.
## Prerequisites
Ensure you have the following installed before proceeding:
- **Go 1.26.1 or higher**: [Download Go](https://golang.org/dl/)
- **yt-dlp**: Required for video download
```bash
pip install yt-dlp
# or download from https://github.com/yt-dlp/yt-dlp/releases
```
- **ffmpeg**: Required for video format conversion
```bash
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
# Windows
# download from https://ffmpeg.org/download.html
```
## Installation
### Install from Source
```bash
git clone <repository-url>
cd mcp
go build -o tencent-video-mcp ./cmd/tencent-video-mcp
sudo mv tencent-video-mcp /usr/local/bin/
```
### Using Go Install
```bash
go install ./cmd/tencent-video-mcp@latest
```
## Configuration
### 1. Create Configuration File
Copy the example configuration:
```bash
cp config.yaml.example config.yaml
```
### 2. Configure Credentials
Edit `config.yaml` or set environment variables:
```yaml
tencent_video:
username: "${TENCENT_VIDEO_USERNAME}"
password: "${TENCENT_VIDEO_PASSWORD}"
```
### 3. Set Environment Variables
```bash
export TENCENT_VIDEO_USERNAME="your_username"
export TENCENT_VIDEO_PASSWORD="your_password"
```
### 4. (Optional) Configure Tool Paths
If yt-dlp or ffmpeg are not in PATH:
```yaml
tools:
ytdlp_path: "/path/to/yt-dlp"
ffmpeg_path: "/path/to/ffmpeg"
```
## Usage
### Start Server
The server communicates via stdio, suitable for integration with MCP clients:
```bash
tencent-video-mcp [config.yaml]
```
If no configuration file is specified, it defaults to `config.yaml` in the current directory.
## MCP Tools
### parse_video_url
Parse Tencent video URL and extract basic information.
**Parameters:**
- `url` (string, required): Tencent video URL
**Example:**
```json
{
"url": "https://v.qq.com/x/cover/..."
}
```
**Response:**
```json
{
"title": "Video Title",
"duration": "10:25",
"description": "Video description...",
"upload_date": "2024-01-15",
"url": "https://v.qq.com/..."
}
```
### get_video_qualities
Retrieve available quality options for a video.
**Parameters:**
- `url` (string, required): Tencent video URL
**Response:**
```json
{
"qualities": [
{
"id": "137",
"label": "1080P",
"resolution": "1080P",
"is_default": true
},
{
"id": "136",
"label": "720P",
"resolution": "720P",
"is_default": false
}
],
"default_index": 0,
"url": "https://v.qq.com/..."
}
```
### download_video
Download a video in specified quality and convert to MP4 format.
**Parameters:**
- `url` (string, required): Tencent video URL
- `quality` (string, optional): Quality level (e.g., "1080P", "720P"), defaults to highest available quality
- `output_path` (string, required): Local file path to save the video
**Example:**
```json
{
"url": "https://v.qq.com/x/cover/...",
"quality": "1080P",
"output_path": "/path/to/video.mp4"
}
```
**Response:**
```json
{
"success": true,
"file_path": "/path/to/video.mp4"
}
```
## Error Handling
All errors include:
- **Error Code**: Numerical code for error type
- **Error Type**: Error category (InputValidationError, AuthenticationError, etc.)
- **Message**: Detailed problem description
- **Suggestions**: Actionable advice to resolve the issue
- **Context**: Additional debugging information
### Error Codes
| Range | Type |
|------|------|
| 1000-1999 | Input validation errors |
| 2000-2999 | Authentication errors |
| 3000-3999 | Download errors |
| 4000-4999 | Conversion errors |
| 5000-5999 | Configuration errors |
## Integration with AI Assistants
### Claude Desktop
Add to `~/.claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"tencent-video": {
"command": "/path/to/tencent-video-mcp",
"args": ["/path/to/config.yaml"],
"env": {
"TENCENT_VIDEO_USERNAME": "your_username",
"TENCENT_VIDEO_PASSWORD": "your_password"
}
}
}
}
```
### Cline (VS Code)
Configure MCP server path and parameters in VS Code settings.
### Other MCP Clients
Any AI client supporting the MCP protocol can use this server.
## Development
### Run Tests
```bash
go test ./... -v
```
### Run Specific Test
```bash
go test ./internal/services/... -v
```
### Build
```bash
go build -o bin/tencent-video-mcp ./cmd/tencent-video-mcp
```
## Troubleshooting
### yt-dlp Not Found
```
Error: yt-dlp is not installed or not accessible
```
**Solution**: Install yt-dlp using pip or download the binary from GitHub.
### ffmpeg Not Found
```
Error: ffmpeg is not installed or not accessible
```
**Solution**: Install ffmpeg using your system package manager.
### Authentication Failed
```
Error: Login failure - check your credentials
```
**Solution**: Verify your Tencent video username and password are correct.
### Download Failed
```
Error: Download failed - network issue
```
**Solution**: Check your network connection and ensure the video is publicly accessible.
## Project Structure
```
mcp/
├── cmd/tencent-video-mcp/main.go # Entry point
├── pkg/types/ # Shared data types
├── internal/
│ ├── config/ # Configuration layer
│ ├── errors/ # Error handling
│ ├── external/
│ │ ├── cmdrunner/ # Command runner
│ │ ├── ytdlp/ # yt-dlp wrapper
│ │ └── ffmpeg/ # ffmpeg wrapper
│ ├── services/
│ │ ├── parser.go # Video parsing service
│ │ ├── downloader.go # Download service
│ │ └── converter.go # Format conversion service
│ └── mcpserver/ # MCP server
│ ├── server.go # JSON-RPC 2.0 server
│ ├── tools.go # Tool definitions
│ └── handlers.go # Tool handlers
├── config.yaml.example # Example configuration
└── README.md # This document
```
## What is MCP?
**Model Context Protocol (MCP)** is an open protocol introduced by Anthropic to standardize communication between AI assistants, external tools, data sources, and services.
### Advantages of MCP
- **Implement once, use everywhere**: A single MCP server can be used by multiple AI clients like Claude Desktop, Cline, and Continue.dev.
- **Standardized interface**: Unified protocol, no need to develop separate integrations for each AI assistant.
- **Bidirectional communication**: Supports requests and notifications.
- **Transport layer agnostic**: Can be transmitted via stdio, HTTP, etc.
This server fully implements the MCP protocol and can be directly called by any AI client supporting MCP.
## License
MIT License - see LICENSE file
## Contributing
Contributions welcome! Please submit issues or pull requests.
