MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

D
Douyin MCP
by @hhy5562877
GitHub Repo(1 stars)

MCP server by hhy5562877

Created 2/17/2026
Updated about 9 hours ago
README
View Source
Repository documentation and setup instructions

Douyin MCP

抖音 MCP (Model Context Protocol) 服务器，为 AI 助手提供访问抖音数据的能力。

项目简介

Douyin MCP 是一个基于 MCP 协议的服务器，允许 AI 助手（如 Claude）直接与抖音平台交互。通过本项目，AI 可以搜索视频、获取视频详情、读取评论、查看用户信息等。

核心特性

  • 本地签名：内置 JavaScript 签名算法，通过 V8 引擎（py_mini_racer）本地生成 a_bogus 签名，无需外部签名服务
  • 完整功能：提供 8 个工具覆盖抖音主要数据获取场景
  • 简单配置：仅需提供抖音 Cookies 即可使用
  • 类型安全：完整的 Python 类型注解和数据模型

功能列表

| 工具 | 功能描述 | 参数 | |------|----------|------| | check_login_status | 检查登录状态 | 无 | | search_videos | 按关键词搜索视频 | keyword, offset, count, sort_type, publish_time | | get_video_detail | 获取视频详情 | aweme_id | | get_video_comments | 获取视频评论 | aweme_id, cursor, count | | get_sub_comments | 获取评论回复 | comment_id, cursor, count | | get_user_info | 获取用户信息 | sec_user_id | | get_user_posts | 获取用户发布的视频 | sec_user_id, max_cursor, count | | get_homefeed | 获取推荐视频流 | tag, count, refresh_index |

环境要求

  • Python 3.14+
  • uv 包管理器（推荐）
  • 有效的抖音登录 Cookies

安装

# 克隆仓库
git clone https://github.com/yourusername/douyinmcp.git
cd douyinmcp

# 安装依赖
uv sync

配置

Cookie 配置

本项目使用 cookies.txt 文件配置 Cookie，不使用环境变量（避免特殊字符导致的问题）。

配置步骤：

  1. 在项目根目录创建 cookies.txt 文件
  2. 将抖音 Cookie 字符串粘贴到文件中（单行，无需引号）
# 创建 cookies.txt 文件
touch cookies.txt

# 编辑文件，粘贴你的 Cookie
vim cookies.txt

获取 Cookies

  1. 打开浏览器，访问 https://www.douyin.com
  2. 登录你的抖音账号
  3. 按 F12 打开开发者工具
  4. 进入 Application → Cookies → https://www.douyin.com
  5. 复制所有 Cookie（格式：key1=value1; key2=value2; ...）
  6. 粘贴到 cookies.txt 文件中

或者使用浏览器插件（如 EditThisCookie）导出 Cookie 字符串。

cookies.txt 文件示例：

sessionid=abc123; ttwid=xxx; passport_csrf_token=yyy; ...

注意：Cookie 必须是单行文本，不要包含换行符。

使用方法

直接运行

# 确保 cookies.txt 文件存在
uv run python main.py

配置 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "douyin": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/douyinmcp", "python", "main.py"]
    }
  }
}

注意：无需配置环境变量，Cookie 从项目根目录的 cookies.txt 文件读取。

配置 Claude Code

在 .mcp.json 中添加 MCP 服务器配置：

{
  "mcpServers": {
    "douyin": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/douyinmcp", "python", "main.py"]
    }
  }
}

工具详细说明

1. check_login_status - 检查登录状态

检查当前 Cookie 是否有效登录。

# 返回示例
{"logged_in": True}

2. search_videos - 搜索视频

按关键词搜索抖音视频。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | keyword | str | 搜索关键词 | 必填 | | offset | int | 分页偏移 | 0 | | count | int | 每页数量 | 10 | | search_channel | str | 搜索类型：general/video/user/live | general | | sort_type | int | 排序：0-综合, 1-最多点赞, 2-最新 | 0 | | publish_time | int | 时间筛选：0-不限, 1-1天内, 7-1周内, 180-半年内 | 0 |

# 搜索美食视频，按点赞数排序
search_videos(keyword="美食", sort_type=1, count=20)

3. get_video_detail - 获取视频详情

通过视频 ID 获取视频详细信息。

| 参数 | 类型 | 说明 | |------|------|------| | aweme_id | str | 视频 ID |

# 获取指定视频详情
get_video_detail(aweme_id="7590719110745525567")

# 返回信息包括：
# - 标题、描述
# - 点赞数、评论数、分享数、收藏数
# - 作者信息
# - 视频封面、下载地址

4. get_video_comments - 获取视频评论

获取视频的评论列表。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | aweme_id | str | 视频 ID | 必填 | | cursor | int | 分页游标 | 0 | | count | int | 每页数量 | 20 |

# 获取视频评论
get_video_comments(aweme_id="7590719110745525567", count=50)

5. get_sub_comments - 获取评论回复

获取某条评论的回复列表。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | comment_id | str | 评论 ID | 必填 | | cursor | int | 分页游标 | 0 | | count | int | 每页数量 | 20 |

# 获取评论的回复
get_sub_comments(comment_id="7590992888545395462")

6. get_user_info - 获取用户信息

获取用户的个人资料。

| 参数 | 类型 | 说明 | |------|------|------| | sec_user_id | str | 用户安全 ID（以 MS4wLjABAAAA 开头）|

# 获取用户信息
get_user_info(sec_user_id="MS4wLjABAAAAG35eRUkDUlhVctlBVKNxjbbqw4Bu...")

# 返回信息包括：
# - 昵称、签名、头像
# - 粉丝数、关注数
# - 获赞数、作品数
# - IP 属地

7. get_user_posts - 获取用户作品

获取用户发布的视频列表。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | sec_user_id | str | 用户安全 ID | 必填 | | max_cursor | str | 分页游标 | "0" | | count | int | 每页数量 | 18 |

# 获取用户的视频作品
get_user_posts(sec_user_id="MS4wLjABAAAA...", count=30)

8. get_homefeed - 获取推荐视频

获取首页推荐视频流。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | tag | str | 内容分类 | "all" | | count | int | 获取数量 | 20 | | refresh_index | int | 刷新索引 | 0 |

支持的分类标签：

  • all - 全部
  • knowledge - 知识
  • sports - 体育
  • auto - 汽车
  • anime - 二次元
  • game - 游戏
  • movie - 影视
  • life_vlog - 生活
  • travel - 旅行
  • mini_drama - 短剧
  • food - 美食
  • agriculture - 三农
  • music - 音乐
  • animal - 萌宠
  • parenting - 亲子
  • fashion - 时尚
# 获取游戏类推荐视频
get_homefeed(tag="game", count=20)

项目结构

douyinmcp/
├── src/
│   ├── __init__.py        # 包初始化
│   ├── models.py          # 数据模型定义
│   ├── token_manager.py   # Token 生成（msToken, webid, verifyFp）
│   ├── sign.py            # 本地签名模块（V8 引擎）
│   ├── douyin.js          # 签名算法（JavaScript）
│   ├── client.py          # API 客户端实现
│   └── server.py          # MCP 服务器及工具定义
├── tests/
│   ├── __init__.py
│   └── test_all.py        # 综合测试套件
├── doc/
│   └── API.md             # API 接口文档
├── main.py                # 程序入口
├── pyproject.toml         # 项目配置
├── cookies.txt            # Cookie 文件（需自行创建）
├── CHANGELOG              # 变更日志
└── README.md              # 本文档

测试

运行综合测试验证所有功能：

# 确保 cookies.txt 存在
uv run python tests/test_all.py

测试输出示例：

============================================================
Douyin MCP - Comprehensive Test Suite
============================================================

Testing check_login_status...
  ✓ check_login_status: logged_in=True

Testing search_videos...
  ✓ search_videos: Found 5 results

Testing get_video_detail...
  ✓ get_video_detail: Got video: 《给大家讲讲...》

Testing get_video_comments...
  ✓ get_video_comments: Got 10 comments

Testing get_sub_comments...
  ✓ get_sub_comments: Got 1 replies

Testing get_user_info...
  ✓ get_user_info: Got user: 大阳

Testing get_user_posts...
  ✓ get_user_posts: Got 10 posts

Testing get_homefeed...
  ✓ get_homefeed: Got 2 videos from feed

Results: 8/8 tests passed
============================================================

技术实现

签名机制

抖音 Web API 使用 a_bogus 参数进行请求签名验证。本项目通过以下方式实现本地签名：

  1. 使用 py_mini_racer 库提供 V8 JavaScript 引擎
  2. 加载 douyin.js 签名算法
  3. 构建完整的浏览器环境 polyfills（document, navigator, window 等）
  4. 调用 get_abogus() 函数生成签名

Token 生成

  • msToken: 128 字符的验证 Token，支持从字节跳动 API 获取或本地生成
  • webid: 19 位数字 ID，支持从服务器获取或本地 UUID 算法生成
  • verifyFp / s_v_web_id: 指纹验证参数，使用 Base36 时间戳 + UUID 格式

请求参数

每个请求包含 31 个通用参数，模拟真实浏览器环境：

  • 设备信息（platform, cpu_core_num, device_memory）
  • 浏览器信息（browser_name, browser_version, engine_name）
  • 屏幕信息（screen_width, screen_height）
  • 网络信息（downlink, effective_type, round_trip_time）

常见问题

Q: Cookie 多久需要更新？

A: 抖音 Cookie 通常有效期较长，但如果遇到 logged_in=False 或请求失败，需要重新获取 Cookie 并更新 cookies.txt 文件。

Q: 为什么不使用环境变量配置 Cookie？

A: 抖音 Cookie 包含大量特殊字符（如 =、;、% 等），在环境变量中配置容易出现解析问题。使用文件配置更可靠。

Q: cookies.txt 文件放在哪里？

A: 放在项目根目录（与 main.py 同级目录）。

Q: 为什么 get_homefeed 返回的视频数量较少？

A: 推荐接口返回的数量取决于抖音服务器，可能需要多次调用并增加 refresh_index 来获取更多内容。

Q: 遇到签名错误怎么办？

A: 签名模块会自动重置 JavaScript 上下文。如果持续失败，请检查 douyin.js 文件是否完整。

Q: 支持哪些 Python 版本？

A: 项目使用 Python 3.14+ 特性，建议使用最新版本。

API 文档

详细的 API 接口文档请参阅 doc/API.md。

依赖项

  • fastmcp - MCP 服务器框架
  • httpx - 异步 HTTP 客户端
  • py-mini-racer - V8 JavaScript 引擎

许可证

MIT License

免责声明

本项目仅供学习和研究使用。使用本项目获取的数据应遵守抖音平台的服务条款和相关法律法规。请勿将本项目用于任何商业用途或违法行为。

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-douyin_mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "hhy5562877-douyin-mcp": { "command": "npx", "args": [ "hhy5562877-douyin-mcp" ] } } }