@the-thing/toutiao-mcp

一个 MCP（Model Context Protocol）服务器，通过 Puppeteer 浏览器自动化向今日头条发布文章：扫码登录、上传封面图、填写标题与正文、点击发布，全程模拟真人操作，无需头条开放平台 API Key。

发布机制学习自 jiaqi-lyu-de/news-autopublish-mcp，并做了精简（去掉新闻抓取模块，只保留头条发布能力）。

---

工作原理

AI 客户端（Claude Desktop / 支持 MCP 的应用）
        │  ① 调用 toutiao_login（返回二维码图片）
        │  ② 用户手机扫码，Cookie 自动保存到 ~/.toutiao-mcp/cookies.json
        │  ③ 调用 toutiao_publish_article(title, content, imagePath)
        ▼
Puppeteer 打开真实浏览器（复用系统 Chrome/Edge）
        ▼
打开头条 → 注入 Cookie 校验登录 → 点击"发布" → 上传封面图 → 填标题正文 → 点击发布

---

快速开始

方式一：一行配置（推荐，无需下载代码）

使用者不需要 clone 代码、不需要 npm install，只需在 MCP 客户端配置里加一段，首次运行由 npx 自动拉取：

{
  "mcpServers": {
    "toutiao": {
      "command": "npx",
      "args": ["-y", "@the-thing/toutiao-mcp@latest"]
    }
  }
}

使用者环境要求（只需满足两点）：

1. 已安装 Node.js 18+（npx 随附）
2. 本机装有 Google Chrome 或 Microsoft Edge（自动探测；或设置环境变量 PUPPETEER_EXECUTABLE_PATH 指向浏览器可执行文件）

登录 Cookie 位置：~/.toutiao-mcp/cookies.json（用户主目录，跨项目共享登录态），登录后自动生成，无需手动配置。

方式二：本地开发（本仓库）

git clone https://github.com/JessYan0913/toutiao-mcp.git
cd toutiao-mcp
npm install
npm run inspect     # 打开 MCP Inspector 调试

---

使用教程

第 1 步：登录（toutiao_login）

调用后会自动弹出浏览器窗口并显示今日头条登录二维码，用手机「今日头条 / 抖音」App 扫码确认：

• 扫码成功后系统自动保存 Cookie，无需其他操作
• 二维码会同时以图片形式返回给 AI 客户端，可直接在对话界面展示
• 最长等待 5 分钟，超时需重新调用

第 2 步：检查登录态（toutiao_check_status，可选但推荐）

用无头浏览器验证当前 Cookie 是否有效，返回 { isLoggedIn: true/false }。已登录时会自动刷新保存最新 Cookie。

第 3 步：发布文章（toutiao_publish_article）

必填参数：

参数	说明	约束
title	文章标题	2~30 个字，超出会被拒绝
content	文章正文	纯文本，自动填入富文本编辑器
imagePath	本地封面图片路径	绝对路径，文件必须存在

发布完成后浏览器窗口会保留约 20 秒，请在浏览器中确认发布结果（建议手动检查一次是否成功上架）。

给 AI 客户端的提示词示例

1. 请帮我登录今日头条（调用 toutiao_login）
2. 确认登录成功后，发布一篇头条文章：
   - 标题：xxx
   - 正文：xxx
   - 封面图：C:\Users\me\Pictures\cover.png
   （调用 toutiao_publish_article）

---

MCP 工具清单

工具	说明	参数
toutiao_login	打开浏览器获取登录二维码并等待扫码，成功后自动保存 Cookie	无
toutiao_check_status	无头浏览器验证当前登录态，已登录时刷新 Cookie	无
toutiao_logout	删除本地 Cookie（登出）	无
toutiao_publish_article	发布文章：封面图 + 标题 + 正文，触发发布	title、content、imagePath（均必填）

---

发布流程原理（七步）

1. 校验图片路径存在、标题字数 2~30
2. 启动有头浏览器 + 抗检测（隐藏 navigator.webdriver、伪装 Chrome UA、真实分辨率）
3. 注入 Cookie → 校验登录态（未登录直接报错）
4. 首页鼠标「移动 → 悬停 → 点击」发布图标，捕获新弹出的发布窗口
5. 上传封面：点击上传区 → 弹窗上传按钮 → FileChooser 注入图片路径 → 等待处理 → 确认
6. 标题输入框三击全选清空后键入；正文富文本编辑器 focus 后键入
7. 点击发布按钮（连点两次兜底），返回成功

---

项目结构

toutiao-mcp
├── client.js               # 冒烟测试：列出已注册工具（node client.js）
├── src
│   ├── server.js           # MCP server 入口（stdio 传输，注册 4 个工具）
│   ├── toutiao
│   │   ├── login.js        # 扫码登录 + 后台轮询监听 + 自动存 Cookie
│   │   ├── status.js       # 登录态判定（无头浏览器）
│   │   ├── logout.js       # 登出（删 Cookie 文件）
│   │   └── publish.js      # 核心：七步发布流程（Puppeteer 自动化）
│   └── utils
│       ├── browser.js      # 浏览器启动：自动探测系统 Chrome/Edge（跨平台）
│       └── cookies.js      # Cookie 持久化（~/.toutiao-mcp/cookies.json）
└── scripts                 # 调试与命令行辅助脚本

---

常见问题排查

现象	原因与处理
报错「未找到可用的 Chrome/Edge 浏览器」	本机未装 Chrome/Edge，或安装位置特殊；安装浏览器，或设置环境变量 PUPPETEER_EXECUTABLE_PATH
报错「未发现登录信息或登录已失效」	Cookie 过期，重新调用 toutiao_login 扫码
发布后浏览器里没有文章	头条前端改版导致选择器失效；需在 src/toutiao/publish.js 顶部 TOUTIAO_CONFIG.selectors 同步更新 CSS 类名
登录后 Cookie 在哪	~/.toutiao-mcp/cookies.json（本地开发模式为项目目录下 cookies.json）

---

风险提示（重要）

• 非官方通道：浏览器自动化模拟人工操作，违反今日头条平台用户协议，账号存在被风控/封禁的风险，请使用小号测试。
• 选择器脆弱：发布流程依赖硬编码 CSS 类名（集中在 src/toutiao/publish.js 顶部 TOUTIAO_CONFIG.selectors），头条前端改版后需同步更新。
• 需要图形环境：登录/发布使用有头浏览器，服务器部署需虚拟显示（如 Windows 桌面、Xvfb）。
• 凭证安全：Cookie 含敏感会话凭证且明文存储，请勿提交到仓库、注意保管。

---

License

ISC