Blacktwist

BlackTwist MCP 服务

BlackTwist MCP（模型上下文协议）服务可让 Claude、Cursor 等 AI 助手和其他兼容 MCP 的客户端与你的 BlackTwist 账户交互——创建帖子、查看分析数据、管理草稿等。

快速开始

连接到 BlackTwist MCP 服务有两种方式：OAuth（推荐用于 claude.ai）或 API Key（适用于桌面客户端和命令行工具）。

选项 A：通过 OAuth 连接（claude.ai）

如果你使用 claude.ai 作为自定义连接器，OAuth 是最简单的方式——无需 API Key。

1. 前往 claude.ai > 设置 > 集成（或添加自定义连接器）
2. 输入 MCP 服务 URL：https://blacktwist.app/api/mcp
3. Claude 会自动发现 OAuth 端点、注册自身，并将你重定向到 BlackTwist 账户登录页面
4. 登录后，连接即建立——Claude 现在可以使用你的 BlackTwist 账户

OAuth 令牌会自动刷新，因此除非你撤销访问权限，否则无需重新进行身份验证。

选项 B：通过 API Key 连接

对于不支持 OAuth 的 Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端，请使用 API Key。

1. 生成 API Key

1. 打开 BlackTwist 并前往 设置（齿轮图标）
2. 点击侧边栏中的 MCP 标签页
3. 点击 创建 API Key，为其命名（例如“Claude Desktop”），然后点击 创建 Key
4. 立即复制该 Key——它之后不会再次显示

2. 配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中：

Claude Desktop（claude_desktop_config.json）：

{
  "blacktwist": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY"
    }
  }
}

你需要使用 node.js v22；如果你正在使用 nvm，请确保使用正确的版本：

{
  "blacktwist": {
    "command": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin/npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY",
      "PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/usr/bin:/bin",
      "NODE_PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/lib/node_modules"
    }
  }
}

Claude Code

在终端中运行：

claude mcp add --transport http blacktwist https://blacktwist.app/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

或者编辑项目根目录中的文件 .mcp.json：

{
  "mcpServers": {
    "blacktwist": {
      "type": "url",
      "url": "https://blacktwist.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor（设置 > MCP）：

• 名称： blacktwist
• 类型： url
• 服务 URL： https://blacktwist.app/api/mcp
• 请求头： Authorization: Bearer YOUR_API_KEY

3. 开始使用

连接后，你可以向 AI 助手提出以下请求：

• “列出我已连接的社交账户”
• “安排明天上午 9 点在 Threads 发布一条帖子，内容是：刚发布了一个新功能！”
• “将我最新的草稿编辑为：更新后的文案，开头更吸引人”
• “在我关于产品发布的主题帖中添加第二条帖子”
• “显示我过去 7 天的分析数据”
• “我的最佳发帖时间是什么时候？”
• “列出我即将发布的定时帖子”
• “为我最新的草稿添加 growth 和 product launch 标签”

---

服务详情

属性	值
URL	https://blacktwist.app/api/mcp
身份验证	OAuth 2.1 (PKCE) 或 Bearer 令牌（API key）
传输方式	Streamable HTTP（无状态）
协议	通过 HTTP POST 使用 JSON-RPC 的 MCP

---

团队上下文（teamId）

大多数工具都接受可选的 teamId 参数，用于将操作限定在特定团队中。

行为：

1. 如果 teamId 是团队 ID，工具将在该团队的上下文中运行（并验证成员身份）。
2. 如果 teamId 是 "personal"，工具将在个人模式下运行（仅处理用户自己的数据，不涉及团队）。
3. 如果省略 teamId，工具将使用用户当前活跃的团队（来自用户设置）。如果没有活跃团队，则等同于 "personal"。

支持 teamId 的工具： list_providers、list_posts、list_drafts、create_post、get_thread、delete_thread、reschedule_thread、list_time_slots、list_tags、get_subscription、get_follow_up_templates 以及所有分析工具。

不支持 teamId 的工具： list_teams（列出所有团队）、get_user_settings（个人设置）、list_viral_templates / list_viral_template_categories（整个账户的内容库）、edit_post / edit_thread / get_thread_follow_up / set_thread_follow_up / get_thread_tags / set_thread_tags / set_thread_auto_repost（通过基于帖子串的访问方式，使用 userCanAccessThread 在内部处理团队授权）。

订阅访问： 需要付费套餐的分析工具会先检查用户自己的订阅。如果用户没有订阅，系统还会检查用户所属团队中是否有任何团队所有者拥有有效套餐。这意味着团队成员可以通过团队所有者的订阅使用付费功能。

---

可用工具

服务商

list_providers

列出所有已连接的社交媒体账户（Threads 和 Bluesky）。

参数	类型	必填	说明
teamId	string	否	团队 ID。如果未提供，则使用活跃团队。传入 "personal" 表示个人账户。设为某个团队时，仅显示关联到该团队的服务商。

返回： 包含 id、provider、providerUserId、providerUsername、displayName、profilePicture 的服务商数组。

注意： 许多其他工具都需要使用此响应中的 providerId（id 字段）或 providerUserId。

---

团队

list_teams

列出用户所属的所有团队，包括用户在团队中的角色以及当前活跃的团队。始终包含一个 "personal" 条目，代表用户的个人账户（非团队账户）。

参数： 无

返回： 包含 id、name、role（OWNER、ADMIN、MEMBER、GUEST）、isActive、createdAt 的团队数组。

个人账户条目的 id 为 "personal"；当当前未选择任何团队时，其 isActive 标记为 true。

注意： 团队 id 可以作为 teamId 传给其他工具（list_posts、list_drafts、create_post 等）。传入 "personal" 可明确使用个人账户。省略 teamId 时，这些工具会自动使用用户当前活跃的团队。

---

帖子与帖子串

create_post

创建一条新帖子或帖子串。帖子串由多条关联在一起的帖子组成。

参数	类型	必填	描述
providerId	string	是	来自 list_providers 的服务商 ID
posts	array	是	帖子对象数组（见下文）
scheduleAt	string	否	ISO 8601 日期时间。如果省略，则保存为草稿。不带时区偏移量的时间（例如 2025-03-15T09:00:00）会按用户配置的时区解释。
autoRepost	object	否	{ enabled: boolean, delays: string[] }，其中延迟时间以小时为单位，例如 ["168", "336"] 表示 7 天和 14 天。如果省略，则应用用户的默认自动转发设置。
teamId	string	否	团队 ID。如果未提供，则使用当前激活的团队。个人账号请传入 "personal"。

自动应用的默认行为：

• 自动转发： 如果未提供 autoRepost，且用户在设置中启用了自动转发，则会将默认延迟应用于第一条帖子。草稿也会应用此设置，因此草稿一经排期仍会保留其延迟时间——reschedule_thread 只会移动 scheduledAt，不会追溯添加延迟时间。
• 跟进内容（自动推广）： 如果该服务商启用了默认跟进模板，则会自动复制并附加到帖子串。发生此情况时，响应会包含 autoPlugApplied: true。
• 时区： 不带偏移量的时间会按用户的 notificationsTimezone 设置解释。带偏移量的时间（Z、+02:00 或 +0200）会作为确切时刻使用，不会查询时区设置。此规则同样适用于 reschedule_thread 和 list_posts。

每个帖子对象：

字段	类型	必填	描述
text	string	是	帖子内容
topic	string	否	主题标签
media	object[]	否	通过公开 URL 添加媒体附件（见媒体附件）
spoilerRanges	object[]	否	文本剧透范围（见剧透）
isSpoilerMedia	boolean	否	如果为 true，则将此帖子中的所有媒体标记为剧透（见剧透）

示例——单条帖子：

{
  "providerId": "clx...",
  "posts": [{ "text": "Hello world!" }],
  "scheduleAt": "2025-03-15T09:00:00"
}

示例——帖子串：

{
  "providerId": "clx...",
  "posts": [
    { "text": "Thread time! Here's what I learned this week 🧵" },
    { "text": "1/ First lesson: consistency beats perfection" },
    { "text": "2/ Second lesson: engage with your community daily" }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

媒体附件

接受 media 的工具（create_post、edit_post、edit_thread、set_thread_follow_up）可以通过公开 URL 附加图片和视频。服务会自动下载媒体、根据 Threads 规范进行验证并上传。

每个媒体对象：

字段	类型	必填	说明
url	string	是	图片或视频的公开 URL
altText	string	否	用于无障碍访问的替代文本

Threads 图片规范：

• 格式：JPEG、PNG
• 最大文件大小：8 MB
• 最大宽高比：10:1

Threads 视频规范：

• 格式：MP4、MOV
• 最大文件大小：1 GB
• 时长：最长 5 分钟
• 最大宽度：1920px

示例 — 发布带图片的帖子：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Check out this view!",
      "media": [
        {
          "url": "https://example.com/photo.jpg",
          "altText": "Sunset over the mountains"
        }
      ]
    }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

剧透内容（仅限 Threads）

在 Threads 上，剧透功能可通过模糊效果隐藏部分文本或媒体。查看者点击后即可显示隐藏内容。

文本剧透定义为一组字符范围：

字段	类型	必填	说明
offset	number	是	字符偏移量（从 0 开始计数）
length	number	是	范围内的字符数

• 每条帖子最多包含 10 个剧透范围
• 范围对应 text 字段中的字符位置

媒体剧透是每条帖子单独设置的布尔标记。当 isSpoilerMedia 为 true 时，帖子中的所有媒体（图片和视频）都会被模糊处理，直到查看者点击显示。

文本剧透和媒体剧透彼此独立 — 帖子可以同时启用两者、只启用其中一项，或都不启用。

示例 — 发布含文本剧透的帖子：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "The winner is John!",
      "spoilerRanges": [{ "offset": 14, "length": 5 }]
    }
  ]
}

示例 — 发布含媒体剧透的帖子：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Spoiler alert! Check the image",
      "media": [{ "url": "https://example.com/reveal.jpg" }],
      "isSpoilerMedia": true
    }
  ]
}

在响应中（list_posts、list_drafts、get_thread），每条帖子都包含：

• spoilerRanges：{ offset, length } 数组（无文本剧透时为空）
• isSpoilerMedia：布尔值（媒体设为剧透时为 true）

---

list_posts

列出指定日期范围内已安排和已发布的帖子。

参数	类型	必填	说明
from	string	是	开始日期（ISO 8601）。不带时区偏移的时间将按用户配置的时区解释。
to	string	是	结束日期（ISO 8601）。不带时区偏移的时间将按用户配置的时区解释。
providerId	string	否	Provider ID（来自 list_providers）。如果提供，则仅返回此 Provider 的帖子。
teamId	string	否	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账号。

list_drafts

列出所有草稿帖子（尚未安排）。

参数	类型	必填	说明
teamId	string	否	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账号。

get_thread

获取指定帖子串及其所有帖子、媒体和分析数据。

参数	类型	必填	说明
threadId	string	是	帖子串 ID
teamId	string	否	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账号。

edit_post

编辑单条帖子的文本内容、主题或媒体。只有状态为 READY 的帖子（草稿或已安排发布的帖子）可以编辑；已发布、正在处理或失败的帖子无法编辑。请先使用 get_thread 获取帖子 ID。

参数	类型	必填	说明
postId	string	是	帖子 ID（来自 get_thread）
content	string	否	新的文本内容
topic	string	否	新的主题标签。传入 null 可移除主题。
media	object[]	否	通过公开 URL 替换所有媒体（参见媒体附件）。省略则保留现有媒体。
spoilerRanges	object[]	否	替换文本剧透范围（参见剧透（仅限帖子串））。省略则保持不变。传入 [] 可全部移除。
isSpoilerMedia	boolean	否	设置媒体剧透标记。true = 模糊显示，false = 移除剧透标记。省略则保持不变。

必须至少提供 content、topic、media、spoilerRanges 或 isSpoilerMedia 中的一项。

返回： postId、threadId、updated（用于指示哪些字段已更改的对象）。

示例 — 更新文本：

{
  "postId": "clx...",
  "content": "Updated post content"
}

示例 — 更新文本并清除主题：

{
  "postId": "clx...",
  "content": "New content",
  "topic": null
}

edit_thread

通过添加、移除或重新排序帖子来编辑帖子串。请提供完整的目标帖子列表——现有帖子（带有 id）会更新，新帖子（不带 id）会创建，而列表中未包含的现有帖子会被移除。只有所有帖子状态均为 READY 的帖子串才能编辑。

参数	类型	必填	说明
threadId	string	是	帖子串 ID
posts	array	是	按顺序排列的帖子数组（至少 1 条）。顺序决定 postOrder（从 0 开始计数）。见下文。

每个帖子对象：

字段	类型	必填	说明
id	string	否	现有帖子的帖子 ID。省略则在该位置创建新帖子。
text	string	是	帖子内容
topic	string	否	主题标签
media	object[]	否	通过公开 URL 附加的媒体（参见媒体附件）
spoilerRanges	object[]	否	文本剧透范围（参见剧透（仅限帖子串））
isSpoilerMedia	boolean	否	若为 true，则此帖子中的所有媒体都会标记为剧透

新帖子会继承现有帖子串的 scheduledAt、provider、providerUserId 和 teamId。

返回： threadId、postsUpdated、postsCreated、postsDeleted、totalPosts。

示例 — 重新排序并添加帖子：

{
  "threadId": "abc123",
  "posts": [
    { "id": "existing-post-2", "text": "Now this is first" },
    { "id": "existing-post-1", "text": "Now this is second" },
    { "text": "Brand new third post" }
  ]
}

示例 — 移除帖子（从列表中省略）：

{
  "threadId": "abc123",
  "posts": [{ "id": "existing-post-1", "text": "Keep only this one" }]
}

delete_thread

永久删除一个线程及其所有帖子。

参数	类型	必填	描述
threadId	string	是	线程 ID
teamId	string	否	团队 ID。若未提供，则使用当前团队。传入 "personal" 表示个人账户。

reschedule_thread

更改线程的计划日期／时间。

参数	类型	必填	描述
threadId	string	是	线程 ID
scheduledAt	string	是	新的日期时间（ISO 8601）。不带时区偏移的时间将按用户配置的时区解释。
teamId	string	否	团队 ID。若未提供，则使用当前团队。传入 "personal" 表示个人账户。

注意： 这只会更改 scheduledAt。它不会为线程添加自动转发延迟，也不会为没有后续帖子的线程添加后续帖子——如需添加，请使用 set_thread_auto_repost 和 set_thread_follow_up。

set_thread_auto_repost

为现有线程设置或移除自动转发。自动转发会在每个延迟时长从发布时起经过后，重新发布线程的第一条帖子。

参数	类型	必填	描述
threadId	string	是	线程 ID
enabled	boolean	是	是否启用自动转发。设为 false 时，将从线程中移除所有延迟。
delays	string[]	否	以小时为单位的延迟时长，使用字符串表示，例如，["168", "336", "720"] 表示 7、14 和 30 天。设为 true 时必填。此参数会替换所有现有延迟，而非在其基础上添加。

延迟时长必须是正整数小时。启用自动转发时，如果 delays 数组为空或未提供，系统会拒绝请求，而不会悄悄清空线程的设置。

返回： threadId、enabled、delays。

使用 get_user_settings 读取用户的默认延迟（autoRepostDelays），并使用 get_thread 查看线程当前的 autoRepostDelay。新帖子会自动采用默认设置——此工具用于事后更改线程设置。

---

标签

标签用于整理帖子（草稿、计划发布和已发布），并可用于筛选应用中的帖子分析视图。标签按工作区划分范围：团队标签与整个团队共享，个人标签则为私有。标签适用于整个线程，而非其中的单条帖子。

list_tags

列出工作区中可用于整理帖子的标签。

参数	类型	必填	描述
teamId	string	否	团队 ID。如果未提供，则使用当前活动团队。个人账户请传入 "personal"。

返回： { tags } — 包含 id、name、color 的标签数组。

get_thread_tags

获取帖子串上的当前标签。

参数	类型	必填	描述
threadId	string	是	要获取标签的帖子串 ID

返回： { threadId, tags }，其中 tags 是 { id, name, color } 数组。

set_thread_tags

设置帖子串上的标签。此工具涵盖设置、更新和移除标签：它会将帖子串现有标签替换为你传入的确切标签集合。

参数	类型	必填	描述
threadId	string	是	要设置标签的帖子串 ID
tagNames	string[]	是	帖子串所需的完整标签集合。替换现有标签，而非追加。尚不存在的名称会自动创建。传入 [] 可移除所有标签。

行为：

• 名称会去除首尾空格、丢弃空条目，并按大小写不敏感的方式删除重复项（"Growth" 和 "growth" 是同一个标签）。
• 新标签名称会在帖子串所属的工作区范围内自动创建（团队帖子串 → 团队标签，个人帖子串 → 个人标签），并自动分配颜色。
• 标签名称最长为 40 个字符。

返回： { threadId, tags } — 帖子串上的最终标签集合。

示例 — 为帖子串添加标签：

{
  "threadId": "abc123",
  "tagNames": ["growth", "product launch"]
}

示例 — 移除所有标签：

{
  "threadId": "abc123",
  "tagNames": []
}

---

分析

所有分析工具都需要 providerUserId（来自 list_providers），并接受可选的 teamId 来限定访问范围。

需要付费套餐： get_metric_timeseries、get_post_analytics、get_follower_growth 和 get_best_time_to_post 需要付费套餐（用户或团队所有者）。免费套餐用户将收到："需要付费套餐才能访问分析功能。请在 https://blacktwist.app#pricing 订阅"。其余工具（get_live_metrics、get_consistency、get_daily_recap、get_recommendations）适用于所有套餐。

日期范围： from 和 to 日期均包含在内。例如，from: "2026-03-01" 和 to: "2026-03-08" 会包含 3 月 1 日至 3 月 8 日结束时的所有数据。

get_live_metrics

获取互动指标及其相较于上一时段的百分比变化。

参数	类型	必填	描述
providerUserId	string	是	服务商用户 ID
from	string	否	开始日期（默认为 7 天前）
to	string	否	结束日期（默认为当前时间）
teamId	string	否	团队 ID。如果未提供，则使用当前活动团队。个人账户请传入 "personal"。

返回： views、likes、replies、reposts、quotes，每项均包含 value 和 percentageChange。

get_metric_timeseries

获取指定日期范围内某项指标的每日数据点。

参数	类型	必填	描述
providerUserId	string	是	服务商用户 ID
metric	enum	是	以下之一：VIEWS、LIKES、REPLIES、REPOSTS、QUOTES、ENGAGEMENT_RATE、FOLLOWERS_COUNT
from	string	是	开始日期（ISO 8601）
to	string	是	结束日期（ISO 8601）
teamId	string	否	团队 ID。如果未提供，则使用当前活动团队。个人账户请传入 "personal"。

get_post_analytics

获取指定日期范围内每篇帖子的互动指标。每篇帖子还包含其线程续帖部分（自回复），因此会完整返回多帖线程。

Parameter	Type	Required	Description
providerUserId	string	Yes	服务商用户 ID
from	string	Yes	开始日期（ISO 8601）
to	string	Yes	结束日期（ISO 8601）
includeThreadParts	boolean	No	在 thread 数组中包含每篇帖子的线程续帖部分（自回复）。默认为 true；传入 false 可省略。
sortBy	enum	No	在 100 篇帖子的上限前对帖子进行排序。可选值：timestamp、views、likes、replies、reposts、quotes、engagementRate。默认为 timestamp。
sortOrder	enum	No	asc 或 desc。默认为 desc。
search	string	No	仅返回正文包含此字符串的帖子（不区分大小写，最多 200 个字符）。
tagNames	string[]	No	仅返回带有这些标签中至少一个的帖子（名称取自 list_tags，不区分大小写，最多 50 个）。未知名称会返回错误。
teamId	string	No	团队 ID。若未提供，则使用当前团队。传入 "personal" 表示个人账户。

返回： posts、count（返回的帖子数）和 total（符合筛选条件的日期范围内帖子数）。排序和筛选会在 100 篇帖子的上限生效前应用于整个日期范围，因此即使日期范围内有数千篇帖子，sortBy: "views" 也会返回实际浏览量最高的帖子；如果未指定 sortBy，则会返回最近的 100 篇帖子。total > count 表示列表已达到上限。

每篇帖子包含 mediaId、text（截断至 200 个字符）、timestamp、permalink、provider 和 analytics（views、likes、replies、reposts、quotes、engagementRate）。每篇帖子还包含一个 thread 数组，其中是根据用户的自回复重建的续帖部分，因此多帖线程会完整返回所有帖子。每个部分包含 replyId、text（截断至 200 个字符）、permalink、timestamp、partOrder（从 2 开始；根帖子为第 1 部分）以及该部分自己的 analytics（views、likes、replies、reposts、quotes、engagementRate）。单篇帖子会返回空的 thread。传入 includeThreadParts: false 可完全跳过重建，并返回空的 thread 数组。

示例：

• 最近 6 个月浏览量最高的 10 篇帖子：设置 sortBy: "views"，然后取前 10 篇。
• 关于某个主题的帖子：search: "morning routine"。
• 某个标签下表现最佳的帖子：tagNames: ["Evergreen"]，sortBy: "engagementRate"。

get_follower_growth

获取随时间变化的每日粉丝数。

Parameter	Type	Required	Description
providerUserId	string	Yes	服务提供方用户 ID
from	string	Yes	开始日期（ISO 8601）
to	string	Yes	结束日期（ISO 8601）
teamId	string	No	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账户。

**返回：**每日 followers 数据点和 totalGrowth。

get_consistency

获取 365 天的发帖规律热力图。

Parameter	Type	Required	Description
providerUserId	string	Yes	服务提供方用户 ID
teamId	string	No	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账户。

返回：days（{ date, count } 数组）、totalPosts、daysWithPosts、currentStreak、recordStreak。

get_daily_recap

获取昨日摘要。

Parameter	Type	Required	Description
providerUserId	string	Yes	服务提供方用户 ID
teamId	string	No	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账户。

返回：date、newFollowers、postsCount。

get_recommendations

根据你的分析数据模式获取发帖建议。

Parameter	Type	Required	Description
providerUserId	string	Yes	服务提供方用户 ID
teamId	string	No	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账户。

返回：bestPostingHoursUtc、topPerformingPosts、currentStreak、recordStreak。

get_best_time_to_post

根据过去 10 周的历史互动数据，获取最佳发布时间。此工具映射了“最佳发布时间”分析图表：按一天中的小时统计互动数据，既提供全周平均值，也按每周的每一天分别细分。小时采用用户自己的时区报告。

需要有效订阅： 此工具需要有效订阅——用户必须拥有自己的付费套餐，或加入由拥有有效订阅的团队所有者管理的团队。否则将返回：“最佳发布时间需要有效订阅。你需要拥有自己的付费套餐，或加入由拥有有效订阅的团队所有者管理的团队。请访问 https://blacktwist.app#pricing 订阅”

时区： 服务端会根据用户的 notificationsTimezone 设置自动解析（默认为 UTC）。MCP 调用方通常无法获知用户的时区，因此应将 timezoneOffset 留空，由系统推导。

参数	类型	必填	描述
providerUserId	string	是	服务提供方用户 ID
timezoneOffset	number	否	时区偏移量的覆盖值，用于对小时进行分组。留空则使用用户配置的账户时区（推荐）。若设置，请使用与 JavaScript 的 Date.getTimezoneOffset() 相同的分钟数（位于 UTC 以东：UTC+2 为 -120）。
view	enum	否	"average"、"daily" 或 "both"（默认值）。选择要返回的细分视图。
teamId	string	否	团队 ID。若未提供，则使用当前团队。个人账户请传入 "personal"。

返回： provider、timezone（IANA 名称；使用覆盖偏移量时为 "custom"）、timezoneOffsetMinutes、timezoneInfo（一条易读的说明，指出所用时区，并链接到 https://blacktwist.app/write?settings=notifications，方便用户在时区错误时进行更正）；以及根据 view 返回的 averageView（包含 bestHours 和全周 24 个小时的 averageEngagement 值）和 dailyView（包含 7 天的数据，每天都有 dayName、bestHour 和 24 个小时的 averageEngagement 值）。

---

跟进（自动插入）

跟进系统会在帖子达到互动阈值（点赞、回复、转发）或经过一段时间后自动回复。

时效： 跟进任务只会评估过去 24 小时内发布的帖子。为一条发布已超过一天的帖子串添加跟进不会生效——跟进永远不会触发。请在帖子发布前或发布后的第一天内添加跟进。

get_follow_up_templates

列出某个服务商的已保存后续跟进模板。

Parameter	Type	Required	Description
userProviderId	string	Yes	来自 list_providers 的服务商 id
teamId	string	No	团队 ID。如果未提供，则使用当前活动团队。个人账户请传入 "personal"。用于限定所包含的团队成员模板。

get_thread_follow_up

获取特定话题串的后续跟进配置。

Parameter	Type	Required	Description
threadId	string	Yes	话题串 ID

set_thread_follow_up

设置或更新话题串的后续跟进配置。这会整体替换话题串的后续跟进配置；未填写的字段将重置为默认值，而不会保留原值。

Parameter	Type	Required	Description
threadId	string	Yes	话题串 ID
isEnabled	boolean	Yes	启用/禁用后续跟进
text	string	No	后续跟进回复文本
images	string[]	No	图片 URL
delayTimeMinutes	number	No	时间延迟触发条件（分钟）
delayTimeMinutesEnabled	boolean	No	启用时间延迟触发条件
numberOfLikes	number	No	点赞数阈值
numberOfLikesEnabled	boolean	No	启用点赞触发条件
numberOfReplies	number	No	回复数阈值
numberOfRepliesEnabled	boolean	No	启用回复触发条件
numberOfReposts	number	No	转发数阈值
numberOfRepostsEnabled	boolean	No	启用转发触发条件
media	object[]	No	通过公开 URL 添加媒体附件（请参阅媒体附件）

---

计划安排

list_time_slots

列出某个服务商配置的发帖时段。时段用于定义首选的计划发布时间。

Parameter	Type	Required	Description
providerId	string	Yes	来自 list_providers 的服务商 id
teamId	string	No	团队 ID。如果未提供，则使用当前活动团队。个人账户请传入 "personal"。

返回：{ timeSlotHour, timeSlotMinute, weekDays } 数组，其中 weekDays 为 [0-6]（0 = 星期日）。

---

爆款模板

浏览从高表现帖子中提取的爆款帖子模板库。每个模板都包含结构、使用说明，以及带有互动指标的原始示例帖子。

**需要付费套餐：**以下两个工具都需要有效的付费套餐（用户拥有的套餐、Lifetime Deal，或加入套餐所有者拥有付费套餐的工作区）。免费套餐用户会收到：“需要付费套餐才能访问爆款帖子模板”。

list_viral_templates

列出爆款帖子模板，支持筛选、全文搜索、排序和分页。

参数	类型	必填	描述
search	string	否	全文搜索。匹配示例帖子文本（不区分大小写）。
category	string	否	按单个类别筛选。使用 list_viral_template_categories 返回的值，或之前响应中的 categories 字段。
sort	enum	否	按示例帖子的互动量排序：views（默认）、likes、replies 或 engagementRate。降序排列。
page	number	否	页码，从 1 开始。默认为 1。
pageSize	number	否	每页条目数（1–50）。默认为 20。超过 50 的值会限制为 50。

返回： { templates, categories, totalCount, page, pageSize }。

每个模板：

字段	类型	描述
id	string	模板 ID
category	string	模板类别
template	string	模板结构
instructions	string	模板使用方法
exampleText	string	原始爆款帖子文本
views	number	示例帖子的浏览量
likes	number	示例帖子的点赞数
replies	number	示例帖子的回复数
engagementRate	number	示例帖子的互动率（点赞数+回复数/浏览量）

list_viral_template_categories

列出所有可用的模板类别及其模板数量。在调用 list_viral_templates 并使用 category 筛选之前，可将此工具用作发现步骤。

参数： 无

返回： { categories: [{ category, templateCount }] }，按类别名称的字母顺序排列。

---

账户

get_subscription

获取当前套餐、剩余发帖额度和账户配额。

参数	类型	必填	描述
teamId	string	否	团队 ID。如果未提供，则使用当前团队。传入 "personal" 表示个人账户。

返回： planType、planName、isFreePlan、remainingPosts、limits（maxTeams、maxMembers、maxAccounts）。

get_user_settings

获取用户设置，包括时区、日期格式和自动转发配置。

参数： 无

返回： notificationsTimezone、dateFormat、autoRepostEnabled、autoRepostDelays 等。

---

常见工作流

在下一个空闲时段安排帖子

1. list_providers → 获取你的服务商 ID
2. list_time_slots → 查找可用时段
3. create_post → 使用下一个时段的时间安排帖子

查看每周表现

1. list_providers → 获取你的服务商用户 ID
2. get_live_metrics → 查看本周与上周的数据
3. get_recommendations → 获取改进建议

编辑现有帖子

1. get_thread → 获取帖子串及其帖子 ID
2. edit_post → 更新指定帖子的文本、主题或媒体

向现有帖子串添加帖子

1. get_thread → 获取当前帖子及其 ID
2. edit_thread → 传入所有现有帖子（包含 ID）以及新帖子（不含 ID）

创建带后续回复的帖子

1. create_post → 创建并安排帖子（返回 threadId）
2. set_thread_follow_up → 添加推广回复

如果服务商已启用默认后续回复模板，create_post 会自动为你添加该模板，只有在需要覆盖模板时才需执行第 2 步。

向现有帖子串添加后续回复或自动转发

1. list_posts 或 list_drafts → 查找帖子串及其 threadId
2. get_follow_up_templates → 查看服务商保存的模板值
3. set_thread_follow_up → 添加回复，并复制模板中的字段
4. set_thread_auto_repost → 设置延迟时间（使用 get_user_settings 获取用户的默认值）

这适用于尚未发布的帖子串，或在过去 24 小时内发布的帖子串。超过此时间后，后续回复任务将不再检查该帖子。

使用标签整理帖子

1. create_post → 创建帖子（返回 threadId）
2. set_thread_tags → 添加标签（例如 ["growth", "tips"]）——系统会自动创建新的标签名称
3. list_tags / get_thread_tags → 查找现有标签或查看帖子串上有哪些标签

---

提示词

MCP 服务内置了提示词 — 可复用的模板，用于引导 AI 助手完成多步骤工作流。在 Claude Desktop 中，在聊天中输入 / 即可访问。在 Claude Code 中，运行 claude prompts 查看提示词列表。

weekly-report

生成每周表现报告，包含互动指标、热门帖子、粉丝增长情况和建议。

参数：

参数	必填	说明
providerUserId	是	你的服务商用户 ID

示例： “为我的 Threads 账号运行 weekly-report 提示词”

content-ideas

根据表现最佳的内容和发帖规律生成帖子创意。

参数：

参数	必填	说明
providerUserId	是	你的服务商用户 ID
topic	否	关注的主题（例如 "productivity"、"startups"）

示例： “给我一些关于营销的内容创意”

optimize-schedule

分析你的发帖规律，并为本周推荐最佳发帖时间表。

参数：

参数	必填	说明
providerUserId	是	你的服务商用户 ID
providerId	是	你的服务商 ID

示例： “帮我优化发帖时间表”

draft-review

检查当前草稿，并在发布前提供改进建议。

参数： 无

示例： “检查我的草稿，并告诉我如何改进”

monthly-recap

生成全面的月度回顾，包含关键指标、热门帖子和增长趋势。

参数：

参数	必填	描述
providerUserId	是	你的服务商用户 ID

示例： “生成我的月度回顾”

---

API 密钥管理

• 创建密钥： Settings > MCP > Create API Key
• 查看密钥： Settings > MCP（显示前缀、创建日期、最后使用时间）
• 删除密钥： 点击任意密钥旁的垃圾桶图标
• 端点： GET/POST/DELETE /api/user/mcp-keys

密钥在存储前会使用 SHA-256 进行哈希处理。原始密钥仅在创建时显示一次。

---

身份验证

MCP 服务支持两种身份验证方式。两者都使用 Authorization: Bearer <token> 标头。

OAuth 2.1（适用于 claude.ai 和支持 OAuth 的客户端）

该服务按照 MCP Authorization 规范 实现 OAuth 2.1 和 PKCE（S256）。支持 OAuth 的客户端（如 claude.ai）会自动处理此流程。

OAuth 端点：

端点	描述
GET /.well-known/oauth-protected-resource	资源元数据（RFC 9728）
GET /.well-known/oauth-authorization-server	授权服务器元数据（RFC 8414）
POST /api/mcp/oauth/register	动态客户端注册（RFC 7591）
GET /api/mcp/oauth/authorize	授权端点
POST /api/mcp/oauth/token	令牌交换和刷新
POST /api/mcp/oauth/revoke	令牌撤销（RFC 7009）

工作原理：

1. 客户端通过 well-known 元数据发现 OAuth 端点
2. 客户端使用动态客户端注册来注册自身
3. 用户会被重定向，以使用自己的 BlackTwist 账户登录（使用现有的 BlackTwist 登录）
4. 登录后，系统会发放授权码，并将其交换为访问令牌和刷新令牌
5. 访问令牌在 1 小时后过期，并使用刷新令牌自动刷新（有效期为 30 天）

API 密钥（适用于桌面客户端和 CLI 工具）

API 密钥是以 bt_mcp_ 为前缀的静态令牌。默认情况下不会过期，适用于不支持 OAuth 的客户端（Claude Desktop、Cursor、Claude Code CLI）。

如何创建和管理密钥，请参阅 API 密钥管理。

---

技术详情

• 端点： POST /api/mcp（JSON-RPC）
• 传输： 来自 @modelcontextprotocol/sdk 的 WebStandardStreamableHTTPServerTransport
• 模式： 无状态（不管理会话）
• 身份验证： 使用 PKCE（S256）的 OAuth 2.1，或通过 Authorization: Bearer <key> 标头传入 API 密钥
• 未通过身份验证的发现： initialize 和 tools/list 可在未通过身份验证的情况下调用，以便 MCP 注册中心（例如 Glama）检查可用工具
• 速率限制： 已通过身份验证的请求限制为每个 IP 每分钟 60 次。未通过身份验证的发现请求限制为每个 IP 每分钟 10 次。
• 源代码： src/libs/mcp/（服务器、身份验证、OAuth、工具），src/app/api/mcp/（路由处理程序、OAuth 端点）