Douyin Video Analysis MCP

# 抖音视频解析 MCP 服务 一个 MCP（Model Context Protocol）服务器，用于解析抖音分享链接并使用豆包视频理解模型进行智能内容分析。 ## 📦 快速安装 ```bash pip install doubao-douyin-analysis-parse-mcp ``` **就这么简单！** 然后[配置 Cursor](#在-cursor-中使用) 即可使用。 > ⚠️ **v1.0.0 用户注意**：v1.0.0 有 bug 无法使用，请查看 [v1.0.0迁移指南.md](v1.0.0迁移指南.md) 升级到 v1.0.1 > 💡 **开发者**：查看[源码安装](#方式-b从源码安装开发者) --- ## 📚 专用配置指南 - 🍒 **[Cherry Studio 配置](Cherry_Studio配置指南.md)** - Cherry Studio 专用指南 - 📋 **[快速参考](快速参考.md)** - 配置速查卡片 - 🔄 **[v1.0.0 迁移](v1.0.0迁移指南.md)** - 从 v1.0.0 升级 --- ## 🎓 新手指南 **如果你是 Python 初学者，请先阅读：** - 📖 **[新手指南.md](新手指南.md)** - 零基础完整教程（推荐） - 🚀 **[调试步骤.md](调试步骤.md)** - 5 分钟快速上手 - ⚡ **[QUICKSTART.md](QUICKSTART.md)** - 快速开始指南 **已经熟悉 Python？** 继续往下看 ↓ --- ## 功能特性 ✨ **智能链接提取** - 自动从抖音口令中提取视频链接 🎥 **视频内容解析** - 获取视频真实 URL 🤖 **AI 视频分析** - 使用豆包大模型进行深度内容分析 📋 **结构化输出** - 返回格式化的视频描述、大纲和教程步骤 ## 项目架构 ``` 抖音口令/链接 → 链接提取 → 抖音API → 视频URL → 豆包AI → 结构化分析结果 ``` ## 分析内容 服务会返回以下结构化内容： - **视频描述**：简短概括（50字以内） - **视频类型**：自动识别（烹饪教程、Vlog、剧情等） - **视频大纲与内容**： - **教程类**：所需材料、详细步骤、重点提示 - **其他类型**：主要内容、关键场景、核心信息 ## 快速开始 ### 🚀 方式 A：从 PyPI 安装（推荐，最简单） **仅需一条命令：** ```bash pip install douyin-mcp-server ``` **就这样！** 无需下载代码，无需配置环境。 然后跳转到 **[配置 API Key](#3-配置环境变量)** 和 **[在 Cursor 中使用](#在-cursor-中使用)** --- ### 🛠️ 方式 B：从源码安装（开发者） #### 1. 环境要求 - Python 3.10 或更高版本 - pip 包管理器 #### 2. 安装依赖 ```bash # 克隆或进入项目目录 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` 文件： ```bash cp env.example .env ``` 编辑 `.env` 文件，设置你的豆包 API Key： ```env 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 1. 访问 [火山引擎控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey) 2. 登录并创建 API Key 3. 将 API Key 复制到 `.env` 文件中 ### 5. 测试服务器 #### 方法 1：运行 MCP 服务器 ```bash python -m src ``` #### 方法 2：运行测试示例 ```bash python test_example.py ``` 测试示例会验证： - 链接提取功能 - 视频 URL 获取功能 - 完整视频信息获取 ## 在 Cursor 中使用 ### 配置步骤 1. 打开 Cursor 设置 2. 找到 MCP 配置区域 3. 添加以下配置： **如果使用 PyPI 安装（推荐）：** ```json { "mcpServers": { "douyin-analyzer": { "command": "douyin-mcp-server", "env": { "DOUBAO_API_KEY": "your_actual_api_key" } } } } ``` > ⚠️ **重要**：PyPI 安装后使用 `"command": "douyin-mcp-server"`，不需要 `args` **如果从源码运行（开发者）：** ```json { "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 安装用户：** ```json { "mcp.servers": { "douyin-analyzer": { "command": "douyin-mcp-server", "env": { "DOUBAO_API_KEY": "your_actual_api_key" } } } } ``` **源码安装用户：** ```json { "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 用户：** ```bash pip install --upgrade douyin-mcp-server ``` **源码用户：** ```bash cd D:\work\my-project\douyin_to_notion git pull pip install -e . --force-reinstall ``` ### 卸载 ```bash 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]` 作为视频播放地址。 示例响应结构： ```json { "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` - **文档**: [豆包视频理解官方文档](https://www.volcengine.com/docs/82379/1895586?lang=zh) ## 常见问题 ### 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。