toutiao-mcp

今日头条创作者平台（mp.toutiao.com）的 MCP 服务：扫码登录 + 图文文章 / 微头条发布。 走登录态浏览器自动化，不需要官方 API。

任意 MCP 客户端都能连（Claude Code、Cursor、n8n、自建 agent），也可作为 Docker 边车接入内容运营系统。

⚠️ 风险须知：头条没有开放的发布 API，本服务模拟人在网页端操作。这可能违反平台用户协议， 账号存在风控甚至封禁的风险。请自行评估，建议先用小号验证。作者不对账号损失负责。

能做什么

不做的事：不生成内容、不做排版主题、不逆向头条私有接口、不做定时与频控（那是调用方的职责）。

Related MCP server: Douyin Creator Platform MCP Server

快速开始

方式一：桌面客户端（stdio）

Claude Code / Cursor 的 MCP 配置里加：

{
  "mcpServers": {
    "toutiao": {
      "command": "npx",
      "args": ["-y", "@moraya/toutiao-mcp", "stdio"],
      "env": { "TOUTIAO_DATA_DIR": "~/.toutiao-mcp" }
    }
  }
}

首次使用先扫码登录（需要图形环境）：

npx -y @moraya/toutiao-mcp login

方式二：Docker（推荐用于服务器 / 接入自动化系统）

cp .env.example .env      # 至少设一个 AUTH_TOKEN
docker compose -f docker/docker-compose.yml up -d
curl http://127.0.0.1:18070/healthz

MCP 端点：http://127.0.0.1:18070/mcp（streamable-http，带 Authorization: Bearer <AUTH_TOKEN>）。

容器里没有图形环境，登录靠 get_login_qrcode 工具：让 agent 调用它、把返回的二维码图片展示给你， 用今日头条 App 扫一下，再调 check_login_status 确认。

方式三：源码运行

pnpm install
npx playwright install chromium
pnpm build
node dist/cli.js serve          # 或 stdio / login / doctor

典型对话

你：帮我把这篇稿子发到头条
Agent：（调 check_login_status → 未登录）
       （调 get_login_qrcode → 展示二维码）请用今日头条 App 扫码
你：（扫码）好了
Agent：（调 check_login_status → 已登录）
       （调 publish_article，2 分钟后）已发布，文章 ID 74123…，链接 https://www.toutiao.com/item/…

给 agent 的提示：发布耗时可达数分钟，请把客户端超时设到 300 秒以上。 返回体里 verified: false 表示没能从平台确认结果 —— 这时内容很可能已经发出去了， 请提示用户去后台核对，不要直接重发。

内容规则（服务端会拦，不会静默截断）

超限一律返回 CONTENT_LIMIT 而不是截断：无人值守下，半截内容「发布成功」比失败糟糕得多。 压缩/改写请在调用侧完成。

注意 publish_article 的 also_weitoutiao 默认为 false：头条发布页默认勾选「同时发布微头条」， 本服务会主动取消，避免一次调用发出两条内容。需要的话显式传 true。

配置

全部环境变量见 .env.example。最常用的几个：

正文插图策略

头条编辑器对「粘贴进来的外链图」是否自动转存，随版本而变。所以做成可切换 + 自动回落：

无论哪条路，发布前都会校验正文里的图是否已经是平台地址 —— 不校验就会出现 「发布成功但图是外链」，这种问题读者比你先发现。

排错

node dist/cli.js doctor    # 浏览器可用性 + 数据目录 + 登录态
docker logs toutiao-mcp    # 日志一律在 stderr

开发

pnpm install && npx playwright install chromium
pnpm test        # 37 项：内容单测 + 假站流程测试 + MCP e2e，全程不碰真站
pnpm lint && pnpm check

测试用本地假站（test/fake-site/）复刻了头条后台的关键 DOM —— 编辑器是真的监听 paste 事件解析 text/html 的 contenteditable，而不是一个 textarea。假站不像真机，等于没测。

平台改版时：改 src/core/selectors.ts（所有 URL 与选择器的唯一出处）→ 跑 pnpm test → 发 patch 版本。

致谢

• xpzouying/xiaohongshu-mcp — 产品形态与工具契约的参考

• jiulingyun/toutiao-ops（MIT）— 头条后台页面流程与选择器的重要参考

License

AGPL-3.0-only