抖音视频解析 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

1. 访问 火山引擎控制台
2. 登录并创建 API Key
3. 将 API Key 复制到 .env 文件中

5. 测试服务器

方法 1：运行 MCP 服务器

python -m src

方法 2：运行测试示例

python test_example.py

测试示例会验证：

• 链接提取功能
• 视频 URL 获取功能
• 完整视频信息获取

在 Cursor 中使用

配置步骤

1. 打开 Cursor 设置
2. 找到 MCP 配置区域
3. 添加以下配置：

如果使用 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。