Content
# Short Video Caption Extractor
[](https://badge.fury.io/py/douyin-mcp-server)
[](https://pypi.org/project/douyin-mcp-server/)
[](https://opensource.org/licenses/Apache-2.0)
Download watermark-free videos from short video sharing links, and automatically extract voice captions using AI.
<a href="https://glama.ai/mcp/servers/@yzfly/douyin-mcp-server">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@yzfly/douyin-mcp-server/badge" alt="douyin-mcp-server MCP server" />
</a>
## ✨ Features
- 🎬 **Watermark-free Video** - Get high-quality watermark-free video download links
- 🎙️ **AI Speech Recognition** - Automatically extract captions using 硅基流动 SenseVoice
- 📑 **Large File Support** - Automatically segment audio files larger than 1 hour or 50MB
- 🌐 **WebUI** - Modern browser interface, no command line required
- 🔌 **MCP Integration** - Supports AI applications such as Claude Desktop
---
## 📦 Usage
| Way | Applicable Scene | Features |
|------|----------|------|
| [**WebUI**](#-webui-recommended) | General users | Browser operation, simplest |
| [**MCP Server**](#-mcp-server) | Claude Desktop users | Directly call in AI conversation |
| [**Command Line**](#️-command-line-tool) | Developers | Batch processing, script integration |
---
## 🌐 WebUI (Recommended)
The easiest way to use, just open the browser.
### Quick Start
```bash
# 1. Clone the project
git clone https://github.com/yzfly/douyin-mcp-server.git
cd douyin-mcp-server
# 2. Install dependencies
uv sync
# 3. Start the service
uv run python web/app.py
```
Open the browser and visit **http://localhost:8080**
### Configure API Key
There are two ways to configure the API Key:
**Method 1: Configure in the browser (recommended)**
1. Open the WebUI page
2. Click the "API Not Configured" button at the top
3. Enter the API Key in the pop-up window and save
4. The API Key is saved locally in the browser and remains valid after refreshing the page
**Method 2: Environment Variables**
```bash
export API_KEY="sk-xxxxxxxxxxxxxxxx"
uv run python web/app.py
```
> 💡 Get a free API Key: [硅基流动](https://cloud.siliconflow.cn/i/TxUlXG3u) (new users have free quota)
### Function Description
| Operation | Description | Requires API |
|------|------|:--------:|
| **Get Info** | Parse video title, ID, get watermark-free download link | ❌ |
| **Extract Text** | Download video → Extract audio → AI speech recognition | ✅ |
| **Download Video** | Click the download link to save the watermark-free video | ❌ |
| **Copy/Download Text** | One-click copy or download Markdown format text | - |
### Usage Steps
1. **Paste Link** - Paste the sharing link into the input box
2. **Click Button** - Select "Get Info" or "Extract Text"
3. **View Results** - Video information and extracted text are displayed on the right
4. **Export** - Copy the text or download the Markdown file
---
## 🚀 MCP Server
Used in applications that support MCP such as Claude Desktop and Cherry Studio.
### Configuration Method
Edit the MCP configuration file and add:
```json
{
"mcpServers": {
"douyin-mcp": {
"command": "uvx",
"args": ["douyin-mcp-server"],
"env": {
"API_KEY": "sk-xxxxxxxxxxxxxxxx"
}
}
}
}
```
### Available Tools
| Tool Name | Function | Requires API |
|--------|------|:--------:|
| `parse_douyin_video_info` | Parse video information | ❌ |
| `get_douyin_download_link` | Get download link | ❌ |
| `extract_douyin_text` | Extract video text | ✅ |
### Dialogue Example
```
User: Help me extract the text of this video https://v.douyin.com/xxxxx/
Claude: I'll help you extract the video text...
[Calling extract_douyin_text tool]
Extraction completed, the text content is as follows:
...
```
---
## 🛠️ Command Line Tool
Suitable for developers and batch processing scenarios.
### Installation
```bash
git clone https://github.com/yzfly/douyin-mcp-server.git
cd douyin-mcp-server
uv sync
```
### Command Description
```bash
# View help
uv run python douyin-video/scripts/douyin_downloader.py --help
# Get video information (no API required)
uv run python douyin-video/scripts/douyin_downloader.py -l "Sharing Link" -a info
# Download watermark-free video
uv run python douyin-video/scripts/douyin_downloader.py -l "Sharing Link" -a download -o ./videos
# Extract text (requires API_KEY)
export API_KEY="sk-xxx"
uv run python douyin-video/scripts/douyin_downloader.py -l "Sharing Link" -a extract -o ./output
# Extract text and save video
uv run python douyin-video/scripts/douyin_downloader.py -l "Sharing Link" -a extract -o ./output --save-video
```
### Output Format
```
output/
└── 7600361826030865707/
├── transcript.md # Text file
└── *.mp4 # Video file (optional)
```
**transcript.md Content:**
```markdown
# Video Title
| Attribute | Value |
|------|-----|
| Video ID | `7600361826030865707` |
| Extraction Time | 2026-01-30 14:19:00 |
| Download Link | [Click to Download](url) |
---
## Text Content
Here is the AI-recognized voice text...
```
---
## 📋 System Requirements
| Dependency | Description | Installation Method |
|------|------|----------|
| uv | Python package management | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Python | 3.10+ | `uv python install 3.12` |
| FFmpeg | Audio and video processing | `brew install ffmpeg` (macOS) <br> `apt install ffmpeg` (Ubuntu) |
---
## 🔧 Technical Notes
### Large File Processing
When the audio file exceeds the API limit (1 hour or 50MB), the following is automatically executed:
1. Detect audio duration and file size
2. Use FFmpeg to split into 9-minute segments
3. Call the API to transcribe segment by segment
4. Merge all text results
### API Description
Speech recognition uses [硅基流动 SenseVoice API](https://cloud.siliconflow.cn/):
- Model: `FunAudioLLM/SenseVoiceSmall`
- Limit: Maximum 1 hour / 50MB per request (automatically processed)
- Cost: New users have free quota
---
## 📝 Changelog
### v1.4.0 (Latest)
- 🌐 **WebUI** - Added browser visual interface
- 🔑 **Browser Configuration API Key** - No environment variables required
- 📑 **Large File Support** - Automatically segment long audio
### v1.3.0
- ✨ Claude Code Skill Support
- 📄 Markdown format output
### v1.2.0
- 🔄 API Upgrade
### v1.0.0
- 🎉 Initial Release
---
## ⚠️ Disclaimer
- This project is for learning and research purposes only
- Users must comply with relevant laws and regulations
- It is forbidden to use it for infringing intellectual property rights
- The author is not responsible for any losses caused by using this project
---
## 📄 License
Apache License 2.0
## 👨💻 Author
**yzfly** - [GitHub](https://github.com/yzfly) | [Email](mailto:yz.liu.me@gmail.com)
