# @the-thing/toutiao-mcp

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

> 发布机制学习自 [jiaqi-lyu-de/news-autopublish-mcp](https://github.com/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 自动拉取：

```json
{
  "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`（用户主目录，跨项目共享登录态），登录后自动生成，无需手动配置。

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

```bash
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