Tiktok Agent Publisher

TikTok Agent 发布器

以 Agent 为先的 TikTok Content Posting API 命令行工具 + MCP。
安全试运行、OAuth 就绪状态检查，为任意 Agent 运行时提供结构化输出。

⭐ 如果这个以 Agent 为先的工具对你的工作流有帮助，请为仓库点个星。 星标能让其他开发者更容易发现这些工具，也能帮助 Delx 持续推出开源基础设施。
🧱 属于 Delx Agent 技术栈 — 涵盖 身体、触达和协调 的 15 个开源 MCP 服务。

---

面向 AI Agent 的本地优先 TikTok Content Posting API 工具。它为 Codex、Claude、Cursor、Hermes、OpenClaw 和其他 MCP 客户端提供安全的方式，用于检查就绪状态、构建 OAuth URL、试运行发布流程，并且仅在明确启用实时模式时上传 TikTok 视频。

当 Agent 需要发布或检查 TikTok 内容，且不想使用浏览器自动化、隐藏状态或泄露令牌时，可以使用它。

存在的意义

大多数社交媒体发布脚本都是为在终端操作的人设计的。Agent 需要不同的约定：

• 说明安装／运行时规则的清单
• 执行写入操作前检查连接状态的工具
• 永不返回令牌值的隐私边界
• 默认采用试运行模式
• 用于规划、重试和审计跟踪的结构化 JSON 输出

本仓库围绕 TikTok 官方的 Content Posting API 封装了这套约定。

安装

npm install -g tiktok-agent-publisher

也可以不安装，直接运行：

npm exec --yes --package=tiktok-agent-publisher -- tiktok-agent-publisher doctor

首篇帖子（试运行）操作指南

无需 TikTok 凭据即可试用。未配置 .env 时，默认启用试运行模式，因此以下每条命令都会返回结构化 JSON，而不会触及线上 API。这是 Agent 在首次实际发布前应遵循的完整流程。以下输出均来自真实 CLI 运行，仅做了少量删减。

1. 检查就绪状态。 doctor 会报告当前模式和仍缺少的内容，绝不会显示任何令牌值。

$ tiktok-agent-publisher doctor
{
  "ok": true,
  "dry_run": true,
  "configured": {
    "client_key": false,
    "client_secret": false,
    "access_token": false,
    "refresh_token": false,
    "public_media_base_url": false,
    "supabase_storage": false
  },
  "missing": [
    "TIKTOK_CLIENT_KEY",
    "TIKTOK_CLIENT_SECRET",
    "TIKTOK_ACCESS_TOKEN",
    "TIKTOK_REFRESH_TOKEN"
  ],
  "ready_for_live_publish": false,
  "ready_for_direct_video_upload": false,
  "next_steps": [
    "Current mode is dry-run. Use dry-run to validate agent workflow before live posting."
  ]
}

2. 确认隐私边界。 privacy-audit 会说明哪些内容保留在本地、哪些内容会发送到 TikTok，以便 Agent 在进行任何写入操作前了解相关约定。

$ tiktok-agent-publisher privacy-audit
{
  "project": "tiktok-agent-publisher",
  "secrets_returned_to_agent": false,
  "token_storage": "Environment variables or local .env with user-only file permissions; tokens are never returned by tools.",
  "safety_rules": [
    "Dry-run is the default.",
    "Only post content the user owns or has permission to publish.",
    "Use explicit confirmation before live direct posting."
  ]
}

3. 构建发布载荷（试运行）。 这会验证任务结构和说明文字，但不会上传任何内容。result.platformPostId 是合成的 dryrun_* ID，且 raw.dryRun 为 true，因此你可以安全地接入重试和审计日志。

$ tiktok-agent-publisher publish-video \
    --video ./short.mp4 \
    --caption "First agent post — testing the dry-run flow" \
    --title "Hello from an agent"
{
  "ok": true,
  "dry_run": true,
  "job": {
    "id": "tiktok_1780082349025",
    "platform": "tiktok",
    "status": "queued",
    "caption": "First agent post — testing the dry-run flow",
    "mediaPaths": ["./short.mp4"],
    "metadata": { "title": "Hello from an agent" }
  },
  "result": {
    "provider": "tiktok_official",
    "platformPostId": "dryrun_1780082349025",
    "raw": { "dryRun": true, "jobId": "tiktok_1780082349025" }
  }
}

4. 轮询状态（试运行）。 publish-status 会返回 DRY_RUN 状态，以便端到端测试轮询循环。

$ tiktok-agent-publisher publish-status --publish-id dryrun_1780082349025
{ "dryRun": true, "publishId": "dryrun_1780082349025", "status": "DRY_RUN" }

5. 列出最近的视频（试运行）。 会返回一个格式良好的空列表，其结构与线上 API 返回的内容相同，因此发布后的确认代码无需修改即可使用。

$ tiktok-agent-publisher list-videos --max-count 5
{ "dryRun": true, "videos": [], "cursor": null, "has_more": false }

开始实际发布。 填写 TIKTOK_CLIENT_KEY / TIKTOK_CLIENT_SECRET（并完成 OAuth——参见 auth-url），确认 doctor 报告 ready_for_live_publish: true，然后设置 TIKTOK_DRY_RUN=false。之后，同样的五条命令就会对接真实的 Content Posting API。

CLI

tiktok-agent-publisher manifest --client codex
tiktok-agent-publisher doctor
tiktok-agent-publisher privacy-audit
tiktok-agent-publisher auth-url --redirect-uri http://localhost:8787/callback
tiktok-agent-publisher publish-video --video ./short.mp4 --caption "Launch copy"
tiktok-agent-publisher publish-status --publish-id <publish_id>
tiktok-agent-publisher list-videos --max-count 10

默认启用试运行模式。只有在 doctor 检查无误且你已准备好调用线上 API 后，才设置 TIKTOK_DRY_RUN=false。

MCP

标准输入输出：

tiktok-agent-mcp

HTTP（v2 无状态）

默认使用 stdio。可选的 Streamable HTTP——无会话 ID，返回 JSON，仅限环回地址：

npx -y -p tiktok-agent-publisher tiktok-agent-mcp --http
# GET  http://127.0.0.1:3031/health
# POST http://127.0.0.1:3031/mcp   (sessionless)

环境变量：TIKTOK_MCP_HOST、TIKTOK_MCP_PORT、TIKTOK_MCP_TRANSPORT=http。

Hermes 风格配置：

mcp_servers:
  tiktok:
    command: npx
    args: ["-y", "tiktok-agent-publisher"]
    sampling:
      enabled: false

建议首先调用：

1. tiktok_connection_status
2. tiktok_privacy_audit
3. tiktok_publish_video

Agent 接口

工具	用途
tiktok_agent_manifest	为 Codex、Claude、Cursor、Hermes 和 OpenClaw 提供安装与运行时指南
tiktok_connection_status	检查试运行、OAuth 和媒体托管就绪状态，不显示令牌值
tiktok_privacy_audit	说明本地文件、令牌和实际发布的边界
tiktok_publish_video	试运行或实际视频发布流程
tiktok_publish_status	轮询发布状态
tiktok_list_videos	用于发布后检查的最近视频列表

可复制粘贴的 Agent 提示词

Use tiktok-agent-publisher. First call tiktok_connection_status and tiktok_privacy_audit.
If dry-run is enabled, build the publish payload only. Do not request or print token values.

配置

将 .env.example 复制为 .env，只填写所需的值。请勿提交 .env、令牌文件或 .agent-data/。

上传视频收件箱中的文件时，可直接通过 TikTok 的上传 URL 上传本地文件。照片和通过 URL 拉取的工作流可使用 Supabase Storage 或其他公共媒体托管服务。

安全模型

• 从环境变量或本地 .env 读取令牌；工具响应绝不包含令牌值。
• 除非设置 TIKTOK_DRY_RUN=false，否则不会启用实际发布。
• OAuth PKCE 验证器会保存在本地 .agent-data/ 中，不会在 MCP 输出中返回。
• 本软件包使用 TikTok 官方 API 接口；不会自动化操作浏览器会话。

开发

npm install
npm test
npm run check

---

📧 联系与支持

• 📨 [email protected] — 一般咨询、集成帮助、合作事宜
• 🐛 错误报告 / 功能请求 — GitHub Issues
• 🐦 动态 — X 上的 @delx369
• 🌐 网站 — wellness.delx.ai