douyin-dm-mcp

一个用于抖音网页版私信的 Model Context Protocol 服务器和本地 HTTP API，基于 Playwright 构建。两个接口复用同一个持久化本地浏览器配置文件，读取当前渲染的会话和消息，并且仅在明确启用时发送单条消息。

该项目使用抖音当前的独立聊天页面：

https://www.douyin.com/chat?isPopup=1

登录和账户状态检查仍使用抖音首页。/messages 当前返回 404 页面，不用于自动化。

安全边界

• DOUYIN_ALLOW_SEND 默认为 false，因此默认禁用真实发送。

• send_message 默认为 dryRun: true。干运行会验证当前快照，而不会打开会话或更改页面状态。

• 真实发送需要同时禁用干运行并设置 DOUYIN_ALLOW_SEND=true。

• 在读取或真实发送之前，服务器会验证昵称唯一、会话位置和确切昵称仍然匹配，以及打开的聊天标题匹配。

• 重复昵称被标记为 targetable: false，MCP 工具和基于昵称的 CLI 都会拒绝。

• 如果点击发送后无法确认结果，服务器返回 SEND_STATUS_UNKNOWN，并且不会自动重试。

• 每个浏览器配置文件都有独占的文件系统锁，以防止并发 Chromium 实例损坏它。MCP、HTTP API 和操作员 CLI 不能同时针对同一个 DOUYIN_PROFILE 运行。

• 所有页面操作都串行化，以防止跨会话读取或发送。

• 该项目不修改浏览器指纹、不绕过验证挑战，也不调用抖音的私有 WebSocket/Protobuf 接口。

• 日志写入 stderr，并编辑消息正文、cookie 和密码字段。

Related MCP server: dy-mcp

当前限制

抖音渲染的会话 DOM 不暴露受支持的稳定会话 ID、用户 ID、sec_uid 或稳定的个人资料链接。因此：

• conversationKey 是不透明的，仅对最新的 list_conversations 快照有效。

• 调用 list_conversations 会创建新键，并立即使上一个快照中的所有键过期。

• 每个会话都返回 stableKey: false；重复昵称还会返回 targetable: false。

• 在调用 read_messages 或 send_message 之前先调用 list_conversations，然后使用该确切结果中的键。

• 会话列表仅包含浏览器当前渲染的项目；complete 始终为 false。

• 模糊昵称匹配、批量发送、陌生人搜索和搜索到发送的回退均有意不支持。

详细的实时页面证据记录在 RESEARCH.md 中。

要求

• Node.js 20 或更高版本

• npm

• 能够显示 Chromium 的桌面环境，用于初始二维码登录

安装

npm install
npx playwright install chromium
npm run build

配置

这些变量从进程环境中读取。项目不加载 .env。请以 .env.example 为参考，然后在 shell 中导出这些值，或在 MCP 客户端的 env 块中设置它们。

浏览器数据存储在：

.data/profiles/<DOUYIN_PROFILE>

此目录包含身份验证数据。请勿提交或共享。

登录

首次使用或会话过期时，运行：

npm run login

使用抖音扫描显示的二维码。登录后，脚本会打印结构化状态，安全关闭 Chromium，并将经过身份验证的会话保留在持久化配置文件中。

检查当前会话：

npm run status

成功结果示例：

{
  "ok": true,
  "browserRunning": true,
  "loggedIn": true,
  "currentUrl": "https://www.douyin.com/jingxuan"
}

启动 MCP 服务器

编译后的入口点是：

node dist/index.js

Codex CLI 示例：

codex mcp add douyin-dm -- node /absolute/path/to/douyin-dm-mcp/dist/index.js

通用 MCP 客户端配置：

{
  "mcpServers": {
    "douyin-dm": {
      "command": "node",
      "args": ["/absolute/path/to/douyin-dm-mcp/dist/index.js"],
      "env": {
        "DOUYIN_PROFILE": "default",
        "DOUYIN_ALLOW_SEND": "false"
      }
    }
  }
}

对于授权的真实发送，请将该 MCP 进程的 DOUYIN_ALLOW_SEND 设置为 true 并重启它。不要全局启用发送。

当 HTTP API 或 CLI 已持有同一配置文件锁时，请勿启动此进程。

启动 HTTP API

从源码运行：

npm run api

或运行编译后的入口点：

node dist/api.js

当 MCP 或 CLI 已持有同一配置文件锁时，请勿启动此进程。

默认基础 URL 是 http://127.0.0.1:3000。未经身份验证的健康检查是：

curl http://127.0.0.1:3000/health

API 路由：

POST 请求需要 Content-Type: application/json。发送默认仍为干运行。真实发送仍需要同时满足 "dryRun": false 和 DOUYIN_ALLOW_SEND=true。

示例：

curl "http://127.0.0.1:3000/api/v1/conversations?limit=20"

curl -X POST http://127.0.0.1:3000/api/v1/messages/read \
  -H "Content-Type: application/json" \
  -d '{"conversationKey":"fallback:...:0","limit":20}'

回环访问不需要 API 密钥。除非 DOUYIN_API_KEY 设置为至少 16 个字符，否则拒绝绑定到任何其他主机。配置后，在每个 /api/v1/* 请求中发送它：

curl http://127.0.0.1:3000/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY"

API 返回与 MCP 相同的结构化成功和抖音错误对象。请求解析错误使用 INVALID_REQUEST、INVALID_JSON、UNSUPPORTED_MEDIA_TYPE 或 PAYLOAD_TOO_LARGE；身份验证失败使用 UNAUTHORIZED。

MCP 工具

browser_status

检查持久化抖音浏览器配置文件是否已通过身份验证。

输入：无。

list_conversations

打开独立聊天页面，并返回当前渲染的会话，以及新快照的不透明 conversationKey 值。

{
  "limit": 20
}

会话字段：

• conversationKey

• stableKey，当前始终为 false

• position

• nickname

• preview

• timestamp

• targetable，当重复昵称导致无法安全选择时为 false

read_messages

从 list_conversations 返回的会话中读取当前可见的消息。

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "limit": 20
}

消息字段：

• direction：incoming 或 outgoing，来自已验证的发送方 DOM 证据

• type：text，或 unsupported 表示无法识别的消息类型

• content：可见文本，为空时为 null

拒绝 targetable: false 的会话。

send_message

向已验证的会话发送一条消息。

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "text": "Test message",
  "dryRun": true
}

真实发送需要满足以下所有条件：

1. DOUYIN_ALLOW_SEND=true。

2. dryRun=false。

3. 目标昵称在当前快照中是唯一的。

4. 会话位置和确切昵称仍与快照匹配。

5. 打开的聊天标题与目标昵称完全匹配。

6. 消息没有前导或尾随空白。

7. 逻辑 Slate 编辑器文本与请求的文本完全匹配。

点击发送后，服务器会等待一条具有确切规范文本的新外发消息。如果确认失败，则返回 SEND_STATUS_UNKNOWN；调用方必须手动检查会话，而不是自动重试。最小发送间隔在会话列表刷新之间保持不变。

操作员 CLI

列出当前渲染的会话：

npm run chat -- list

按确切且唯一的昵称读取消息：

npm run chat -- read "Exact nickname"

真实发送还需要 DOUYIN_ALLOW_SEND。PowerShell 示例：

$env:DOUYIN_ALLOW_SEND="true"
npm run chat -- send "Exact nickname" "Test message"
Remove-Item Env:DOUYIN_ALLOW_SEND

CLI 仅接受确切昵称，当找不到匹配或多个匹配时拒绝继续。

当 MCP 或 HTTP API 已持有同一配置文件锁时，请勿运行 CLI。

开发

npm run lint
npm test
npm run build
npm run smoke:mcp

测试涵盖配置解析、结构化错误、配置文件锁定、页面操作串行化、快照过期、重复拒绝、目标验证、消息方向、干运行隔离、编辑器回滚、成功发送确认、未知发送状态、持久化速率限制和包安全默认值。

项目结构

src/
  browser/          Browser lifecycle, profile locking, and operation serialization
  douyin/           DouyinService, centralized selectors, and page objects
  index.ts          MCP stdio server
  api.ts            HTTP API process entry point
  api/              Versioned HTTP routes, validation, and authentication
scripts/
  login.ts          QR-code login
  status.ts         Authentication status check
  chat.ts           Operator CLI
  mcp-smoke.ts      MCP transport smoke check
tests/unit/         Repeatable behavioral tests
RESEARCH.md         Live-page evidence and engineering research

许可证

根据宽松的 MIT 许可证 许可。