Skip to main content
Glama

Douyin MCP 🎬

抖音 (Douyin / 中国版 TikTok) MCP 服务器 —— 让 Claude 等 AI 助手直接访问抖音数据:搜索视频、视频详情、评论、用户资料、推荐流。

基于 FastMCP + Python,内置本地签名,不依赖任何外部服务。

✨ 特性

  • 本地签名:内置 JavaScript 签名算法,通过 V8 引擎 (py-mini-racer) 本地生成 a_bogus 签名,无需外部签名服务

  • 8 个工具:覆盖抖音主要数据获取场景(搜索 / 详情 / 评论 / 用户 / 推荐流)

  • 零配置复杂度:仅需提供抖音 Cookies 即可使用

  • 类型安全:完整的 Python 类型注解和 dataclass 数据模型

Related MCP server: douyin-mcp-server

🛠 工具一览

工具

功能

关键参数

check_login_status

检查当前登录态

无

search_videos

按关键词搜索视频

keyword, offset, count, search_channel, 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

获取推荐流(支持 16 个内容分类)

tag, count, refresh_index

关于「下载」:本项目提供获取视频播放直链的能力 —— get_video_detail 返回的 video_download_url 即无水印播放地址,图文帖返回 images 图片直链。拿到直链后可用 curl、浏览器或任意下载器自行下载,项目本身不包含「下载到本地文件」的工具。

📦 环境要求

  • Python 3.14+

  • uv 包管理器(推荐)

  • 有效的抖音登录 Cookies

🚀 安装

# 克隆仓库
git clone https://github.com/kaleburannengsha-hue/douyin-mcp.git
cd douyin-mcp

# 安装依赖
uv sync
  1. 浏览器登录 www.douyin.com

  2. 按 F12 → 应用 (Application) → Cookies → https://www.douyin.com

  3. 将全部 Cookie 拼接为一行 key1=value1; key2=value2; ...(用分号+空格分隔),粘贴到项目根目录的 cookies.txt

# 创建 cookies.txt(参考 cookies.txt.example)
touch cookies.txt
# 将 Cookie 字符串粘贴进去(单行,无需引号)

⚠️ 安全提醒:cookies.txt 已在 .gitignore 中排除。Cookie 等同账号凭证,泄露 = 账号被盗风险,切勿提交到任何仓库或分享给他人。

🔌 接入 MCP 客户端

Claude Desktop

编辑 Claude Desktop 的 claude_desktop_config.json:

{
  "mcpServers": {
    "douyin": {
      "command": "uv",
      "args": ["run", "--directory", "D:/path/to/douyin-mcp", "douyinmcp"]
    }
  }
}
  • Windows 配置文件路径:%APPDATA%\Claude\claude_desktop_config.json

  • macOS 配置文件路径:~/Library/Application Support/Claude/claude_desktop_config.json

  • --directory 指向本仓库路径,uv 会自动读取 .python-version 创建虚拟环境

Claude Code / Codex

claude mcp add douyin -- uv run --directory /path/to/douyin-mcp douyinmcp

直接运行

uv run douyinmcp   # 以 stdio 方式启动 MCP 服务器

🧪 测试

uv run python tests/test_all.py

测试覆盖全部 8 个工具,需要先配置好 cookies.txt。

🏗 项目结构

douyin_mcp/
├── main.py              # 入口:启动 MCP 服务器
├── pyproject.toml       # 项目配置(uv)
├── cookies.txt.example  # Cookie 配置模板
├── src/
│   ├── server.py        # FastMCP 服务器与 8 个工具定义
│   ├── client.py        # 抖音 API 客户端
│   ├── models.py        # dataclass 数据模型
│   ├── sign.py          # 本地 a_bogus 签名(V8 引擎)
│   ├── douyin.js        # 内嵌签名算法 JS
│   └── token_manager.py # msToken / webid / verify_fp 生成
├── doc/
│   └── API.md           # 底层接口参考文档(MediaCrawlerPro 整理,部分章节为旧版签名服务,已改用本地签名)
└── tests/
    └── test_all.py      # 8 工具全量测试

⚠️ 免责声明

  • 本项目仅供学习研究使用,请勿用于商业用途或大规模抓取

  • 请遵守抖音平台服务条款及相关法律法规,尊重创作者版权

  • 本项目与抖音 / 字节跳动无任何关联,非官方项目

  • 平台接口与风控策略可能随时变化,可能导致功能失效或账号受限,使用风险自负

📄 License

MIT

Available Tools

8 tools
check_login_statusA

Check if the current Douyin session is logged in.

Returns: dict with 'logged_in' boolean status

Inputs: no named parameters. Returns: object

get_homefeedB

Get recommended videos from Douyin home feed.

Args: tag: Content category - one of: "all", "knowledge", "sports", "auto", "anime", "game", "movie", "life_vlog", "travel", "mini_drama", "food", "agriculture", "music", "animal", "parenting", "fashion" count: Number of videos to return (default 20) refresh_index: Refresh index for pagination (default 0)

Returns: dict containing recommended video list

Inputs: tag, count, refresh_index. Returns: object

get_sub_commentsA

Get replies (sub-comments) for a Douyin comment.

Args: comment_id: The parent comment ID cursor: Pagination cursor (default 0) count: Number of replies per page (default 20) source_keyword: Optional search keyword (used for referer)

Returns: dict containing replies list and pagination metadata

Inputs: comment_id (required), count, cursor, source_keyword. Returns: object

get_user_infoA

Get Douyin user profile information.

Args: sec_user_id: The user's security ID (starts with MS4wLjABAAAA)

Returns: dict containing user profile with nickname, avatar, follower count, following count, total likes, and video count

Inputs: sec_user_id (required). Returns: object

get_user_postsA

Get videos posted by a Douyin user.

Args: sec_user_id: The user's security ID max_cursor: Pagination cursor (default "0") count: Number of videos per page (default 18)

Returns: dict containing video list and pagination info

Inputs: sec_user_id (required), count, max_cursor. Returns: object

get_video_commentsA

Get comments for a Douyin video.

Args: aweme_id: The video/aweme ID cursor: Pagination cursor (default 0) count: Number of comments per page (default 20) source_keyword: Optional search keyword (used for referer)

Returns: dict containing comments list and pagination metadata

Inputs: aweme_id (required), count, cursor, source_keyword. Returns: object

get_video_detailA

Get detailed information about a Douyin video.

Args: aweme_id: The video/aweme ID (numeric string)

Returns: dict containing video details including title, description, statistics (likes, comments, shares), author info, and URLs

Inputs: aweme_id (required). Returns: object

search_videosA

Search for Douyin videos by keyword.

Args: keyword: Search keyword offset: Pagination offset (default 0) count: Number of results per page (default 10, max 20) search_channel: Search type - "general", "video", "user", or "live" sort_type: Sort order - 0 (general), 1 (most liked), 2 (latest) publish_time: Time filter - 0 (unlimited), 1 (1 day), 7 (1 week), 180 (6 months)

Returns: dict containing search results with video list

Inputs: keyword (required), count, offset, sort_type, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: comments vs sub-comments, user info vs user posts, video detail vs video comments, search vs home feed. The only potential overlap is search_videos accepting a 'user' channel, but it still operates by keyword while get_user_info requires a sec_user_id, so no practical confusion.

    Naming Consistency4/5

    All tools use snake_case with a consistent verb_noun pattern (get_*, check_*, search_*). The only minor deviation is 'get_homefeed' (one word) rather than 'get_home_feed', but it remains readable and consistent with the overall convention.

    Tool Count5/5

    Eight tools is well-scoped for a read-only Douyin data access server, covering login, content retrieval, user data, comments, and search without excessive fragmentation or missing obvious categories.

    Completeness4/5

    Core read operations are covered: login status, video detail, comments, replies, user profile, user posts, home feed, and search. Minor gaps include a dedicated user search (search_videos overlaps but is named for videos) and follower/following lists, but these are workable for typical browsing and scraping tasks.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      Provides access to Douyin (TikTok China) API for searching videos, retrieving user profiles, posts, comments, music, challenges, live streams, and hot trends through the Douyin platform.
      79
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to automatically upload videos to Douyin (TikTok China) creator platform, supporting login, video upload with title/description/tags, and session management.
      35
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to access Douyin (TikTok China) data including video search, details, comments, and user information via local JavaScript signature.
      8
      17
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables local scraping and interaction with Douyin (TikTok China) content, including videos, user data, comments, live streams, and private messages, using personal account cookies without official APIs.
      1
      -