抖音视频解析 MCP 服务
一个 MCP（Model Context Protocol）服务器，用于解析抖音分享链接并使用豆包视频理解模型进行智能内容分析。
📦 快速安装
pip install doubao-douyin-analysis-parse-mcp
就这么简单！ 然后配置 Cursor 即可使用。
⚠️ v1.0.0 用户注意：v1.0.0 有 bug 无法使用，请查看 v1.0.0迁移指南.md 升级到 v1.0.1
💡 开发者：查看源码安装
📚 专用配置指南
- 🍒 Cherry Studio 配置 - Cherry Studio 专用指南
- 📋 快速参考 - 配置速查卡片
- 🔄 v1.0.0 迁移 - 从 v1.0.0 升级
🎓 新手指南
如果你是 Python 初学者，请先阅读：
- 📖 新手指南.md - 零基础完整教程（推荐）
- 🚀 调试步骤.md - 5 分钟快速上手
- ⚡ QUICKSTART.md - 快速开始指南
已经熟悉 Python？ 继续往下看 ↓
功能特性
✨ 智能链接提取 - 自动从抖音口令中提取视频链接
🎥 视频内容解析 - 获取视频真实 URL
🤖 AI 视频分析 - 使用豆包大模型进行深度内容分析
📋 结构化输出 - 返回格式化的视频描述、大纲和教程步骤
项目架构
抖音口令/链接 → 链接提取 → 抖音API → 视频URL → 豆包AI → 结构化分析结果
分析内容
服务会返回以下结构化内容：
- 视频描述：简短概括（50字以内）
- 视频类型：自动识别（烹饪教程、Vlog、剧情等）
- 视频大纲与内容：
- 教程类：所需材料、详细步骤、重点提示
- 其他类型：主要内容、关键场景、核心信息
快速开始
🚀 方式 A：从 PyPI 安装（推荐，最简单）
仅需一条命令：
pip install douyin-mcp-server
就这样！ 无需下载代码，无需配置环境。
然后跳转到 配置 API Key 和 在 Cursor 中使用
🛠️ 方式 B：从源码安装（开发者）
1. 环境要求
- Python 3.10 或更高版本
- pip 包管理器
2. 安装依赖
# 克隆或进入项目目录
cd douyin_to_notion
# 创建虚拟环境（推荐）
python -m venv venv
# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# 安装依赖
pip install -e .
3. 配置环境变量
复制 env.example 创建 .env 文件：
cp env.example .env
编辑 .env 文件，设置你的豆包 API Key：
DOUBAO_API_KEY=your_actual_api_key_here
DOUBAO_API_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
DOUBAO_MODEL=doubao-1.5-vision-pro-32k
4. 获取豆包 API Key
- 访问 火山引擎控制台
- 登录并创建 API Key
- 将 API Key 复制到
.env文件中
5. 测试服务器
方法 1：运行 MCP 服务器
python -m src
方法 2：运行测试示例
python test_example.py
测试示例会验证：
- 链接提取功能
- 视频 URL 获取功能
- 完整视频信息获取
在 Cursor 中使用
配置步骤
- 打开 Cursor 设置
- 找到 MCP 配置区域
- 添加以下配置：
如果使用 PyPI 安装（推荐）：
{
"mcpServers": {
"douyin-analyzer": {
"command": "douyin-mcp-server",
"env": {
"DOUBAO_API_KEY": "your_actual_api_key"
}
}
}
}
⚠️ 重要：PyPI 安装后使用
"command": "douyin-mcp-server"，不需要args
如果从源码运行（开发者）：
{
"mcpServers": {
"douyin-analyzer": {
"command": "python",
"args": ["-m", "src"],
"env": {
"DOUBAO_API_KEY": "your_actual_api_key"
},
"cwd": "D:\\work\\my-project\\douyin_to_notion"
}
}
}
使用方法
配置完成后，在 Cursor 中可以通过自然语言调用：
示例 1：使用口令
分析这个抖音视频：0.05 09/23 III:/ e@B.tE 今年农户都不易啊，水产水果都滞销 # 螃蟹 # 国庆假期 https://v.douyin.com/DGHl69ciWp4/ 复制此链接，打开Dou音搜索，直接观看视频！
示例 2：使用链接
帮我分析这个抖音视频的内容：https://v.douyin.com/DGHl69ciWp4/
返回结果示例
对于烹饪教程视频，可能返回：
✓ 成功提取链接: https://v.douyin.com/DGHl69ciWp4/
✓ 成功获取视频 URL
✓ 视频分析完成
==================================================
【视频描述】
展示家常红烧肉的制作过程，简单易学的传统做法
【视频类型】
烹饪教程
【视频大纲与内容】
- 所需食材：
五花肉500g、冰糖30g、生抽2勺、老抽1勺、料酒2勺、葱姜蒜适量
- 操作步骤：
1. 五花肉切块焯水去腥
2. 锅中炒糖色至焦糖色
3. 加入肉块翻炒上色
4. 加入调料和热水，大火烧开转小火炖40分钟
5. 大火收汁装盘
- 重点提示：
炒糖色时火候要掌握好，避免炒糊；炖煮时要用小火慢炖，让肉质更软烂
在 VSCode 中使用
配置步骤
VSCode 配置文件位置：
- Windows:
%APPDATA%\Code\User\settings.json - macOS:
~/Library/Application Support/Code/User/settings.json - Linux:
~/.config/Code/User/settings.json
在 settings.json 中添加：
PyPI 安装用户：
{
"mcp.servers": {
"douyin-analyzer": {
"command": "douyin-mcp-server",
"env": {
"DOUBAO_API_KEY": "your_actual_api_key"
}
}
}
}
源码安装用户：
{
"mcp.servers": {
"douyin-analyzer": {
"command": "python",
"args": ["-m", "src"],
"env": {
"DOUBAO_API_KEY": "your_actual_api_key"
},
"cwd": "D:\\work\\my-project\\douyin_to_notion"
}
}
}
使用方法与 Cursor 相同。
🔄 更新与卸载
更新到最新版本
PyPI 用户：
pip install --upgrade douyin-mcp-server
源码用户：
cd D:\work\my-project\douyin_to_notion
git pull
pip install -e . --force-reinstall
卸载
pip uninstall douyin-mcp-server
项目结构
douyin_to_notion/
├── src/
│ ├── __init__.py # 包初始化
│ ├── __main__.py # 主入口
│ ├── douyin_mcp_server.py # MCP 服务器核心
│ ├── link_extractor.py # 链接提取模块
│ ├── douyin_api.py # 抖音 API 客户端
│ ├── doubao_api.py # 豆包 API 客户端
│ └── prompts.py # 提示词模板
├── pyproject.toml # 项目配置
├── .gitignore # Git 忽略文件
├── env.example # 环境变量示例
├── mcp_config.json # MCP 配置示例
├── cursor_mcp_settings.md # Cursor 配置说明
└── README.md # 本文件
API 说明
抖音解析 API
- 端点:
http://175.24.234.153:8091/api/hybrid/video_data - 方法: GET
- 参数:
url: 抖音视频链接minimal: false
- 返回: 包含视频真实 URL 的 JSON 数据
视频链接提取逻辑：
从返回的 data.video.bit_rate 数组中，选择 bit_rate 值最小的对象（最小码率，文件最小），然后获取该对象的 play_addr.url_list[0] 作为视频播放地址。
示例响应结构：
{
"code": 200,
"data": {
"video": {
"bit_rate": [
{
"bit_rate": 1329070,
"play_addr": {
"url_list": ["视频地址1", "视频地址2"]
}
},
{
"bit_rate": 2598694,
"play_addr": {
"url_list": ["视频地址3", "视频地址4"]
}
}
]
}
}
}
系统会自动选择 bit_rate 为 1329070 的视频地址（最小码率）。
豆包视频理解 API
- 端点:
https://ark.cn-beijing.volces.com/api/v3/chat/completions - 方法: POST
- 认证: Bearer Token
- 模型:
doubao-1.5-vision-pro-32k - 文档: 豆包视频理解官方文档
常见问题
1. 无法提取链接
问题：提示"无法从文本中提取抖音链接"
解决：
- 确保文本中包含完整的抖音链接，格式为
https://v.douyin.com/xxx/ - 检查链接是否被截断
2. API Key 错误
问题：提示"未设置豆包 API Key"
解决：
- 确保在 MCP 配置的
env中设置了DOUBAO_API_KEY - 或者在项目根目录创建
.env文件并设置环境变量
3. 豆包 API 调用失败
问题：豆包 API 返回错误
解决：
- 检查 API Key 是否正确
- 确认账户有足够的配额
- 检查网络连接
- 查看错误信息中的详细提示
4. 抖音 API 无法访问
问题：无法获取视频 URL
解决：
- 检查抖音解析 API 服务是否可用
- 确认网络可以访问该 API 地址
- 尝试使用其他抖音解析服务
技术栈
- Python 3.10+ - 编程语言
- MCP SDK - Model Context Protocol 支持
- httpx - 异步 HTTP 客户端
- python-dotenv - 环境变量管理
- 豆包大模型 - 视频理解和内容分析
开发计划
- 支持批量视频分析
- 添加缓存机制
- 支持自定义提示词
- 添加更多视频平台支持
- 提供 Web 界面
许可证
MIT License
贡献
欢迎提交 Issue 和 Pull Request！
联系方式
如有问题或建议，请提交 Issue。