BlackTwist MCP

BlackTwist MCP服务器

BlackTwist MCP（模型上下文协议）服务器允许Claude、Cursor和其他MCP兼容客户端等AI助手与您的BlackTwist帐户进行交互，包括创建帖子、检查分析、管理草稿等。

快速开始

有两种方法可以连接到BlackTwist MCP服务器： 认证 （推荐给claude.ai）或 API密钥 （适用于桌面客户端和CLI工具）。

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

如果你正在使用 claude.ai 作为一个自定义连接器，OAuth是最简单的选择-不需要API密钥。

1. 首选 claude.ai > 设置 > 集成 （或添加自定义连接器）
2. 输入MCP服务器URL： https://blacktwist.app/api/mcp
3. Claude将自动发现OAuth端点，注册自己，并重定向您使用BlackTwist帐户登录
4. 登录后，连接就建立了——克劳德现在可以使用你的BlackTwist帐户了

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

选项B：通过API密钥连接

对于 克劳德桌面版, 克劳德代码, 光标和其他不支持OAuth的MCP客户端使用API密钥。

1.生成API密钥

1. 打开 BlackTwist 的 并前往 设置 （齿轮图标）
2. 点击 主控程序 侧边栏中的选项卡
3. 点击 创建API密钥，为其命名（例如“Claude Desktop”），然后单击 创建密钥
4. 立即复制密钥，它不会再次显示

2.配置您的MCP客户端

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

克劳德桌面版 (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//.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//.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/usr/bin:/bin",
      "NODE_PATH": "/Users//.nvm/versions/node/v22.22.0/lib/node_modules"
    }
  }
}

克劳德代码

在终端中运行：

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"
      }
    }
  }
}

光标 （设置>MCP）：

• 姓名： blacktwist
• 类型： url
• 服务器URL: https://blacktwist.app/api/mcp
• 标题： Authorization: Bearer YOUR_API_KEY

3.开始使用它

连接后，您可以向您的AI助手询问以下问题：

• “列出我的关联社交帐户”
• “明天上午9点在Threads上安排一篇帖子，说：刚刚发布了一项新功能！”
• “编辑我的最新草稿，说：用更好的钩子更新副本”
• “在我的帖子中添加第二篇关于产品发布的帖子”
• “显示我过去7天的分析”
• “我最好的发帖时间是什么时候？”
• “列出我即将发布的计划帖子”

______________________________________________________________________

服务器详细信息

______________________________________________________________________

团队背景(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, 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 （基于线程的访问通过以下方式在内部处理团队身份验证 userCanAccessThread).

订阅访问权限： 需要付费计划的分析工具将首先检查用户自己的订阅。如果用户没有，系统还会检查用户所属的任何团队所有者是否有活动计划。这意味着团队成员可以通过团队所有者的订阅访问付费功能。

______________________________________________________________________

可用工具

提供商

list_providers

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

退货： 一系列供应商 id, provider, providerUserId, providerUsername, displayName, profilePicture.

注： 许多其他工具需要 providerId （the id 字段）或 providerUserId 从这个回答。

______________________________________________________________________

团队

list_teams

列出用户所属的所有团队，包括他们的角色和当前处于活动状态的团队。始终包括a "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

创建新帖子或帖子。一个帖子是链接在一起的多个帖子。

自动应用的默认行为：

• 自动转发： 如果 autoRepost 如果未提供，并且用户在设置中启用了自动转发，则默认延迟将应用于第一篇帖子。
• 跟进（自动插入）： 如果提供者启用了默认的后续模板，则会自动将其复制并附加到线程。回应包括 autoPlugApplied: true 当这种情况发生时。
• 时区： 没有偏移的时间在用户的 notificationsTimezone 设置。

每个帖子对象：

示例——单篇帖子：

{
  "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规范进行验证，并自动上传。

每个媒体对象：

线程图像规格：

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

视频规格：

• 格式：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上的模糊效果后面隐藏部分文本或媒体。观众点击以显示隐藏的内容。

文本破坏者 被定义为字符范围数组：

• 每根立柱最多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：boolean(true 如果媒体被破坏了）

______________________________________________________________________

list_posts

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

list_drafts

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

get_thread

获取一个包含所有帖子、媒体和分析的特定帖子。

edit_post

编辑单个帖子的文本内容、主题或媒体。只有具有状态的帖子 READY （草稿或计划）可以编辑——发布、处理或失败的帖子都会被拒绝。使用 get_thread 首先检索帖子ID。

至少其中之一 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 可以编辑。

每个帖子对象：

新帖子继承 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

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

reschedule_thread

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

______________________________________________________________________

分析

所有分析工具都需要 providerUserId （从 list_providers)并接受可选 teamId 范围访问。

需要付费计划： get_metric_timeseries, get_post_analytics，以及 get_follower_growth 需要付费计划（用户或团队所有者）。免费计划用户将获得： _“需要付费计划才能访问分析”_.其余工具(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

获取与前一时期相比的百分比变化的参与度指标。

退货： views, likes, replies, reposts, quotes --每个与 value 和 percentageChange.

get_metric_timeseries

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

get_post_analytics

获取日期范围内帖子的每帖子参与度指标。

退货： 最多100个帖子 views, likes, replies, reposts, quotes, engagementRate.

get_follower_growth

随着时间的推移，获取每日关注者数量。

退货： 日常 followers 数据点和 totalGrowth.

get_consistency

获取365天发布一致性热图。

退货： days （数组 { date, count }), totalPosts, daysWithPosts, currentStreak, recordStreak.

get_daily_recap

获取昨天的总结。

退货： date, newFollowers, postsCount.

get_recommendations

根据您的分析模式获取发布建议。

退货： bestPostingHoursUtc, topPerformingPosts, currentStreak, recordStreak.

______________________________________________________________________

随访（自动插电）

在达到参与阈值（点赞、回复、转发）或时间延迟后，跟进系统会自动回复您的帖子。

get_follow_up_templates

列出为提供者保存的后续模板。

get_thread_follow_up

获取特定线程的后续配置。

set_thread_follow_up

设置或更新线程的后续操作。

______________________________________________________________________

调度

list_time_slots

列出为提供商配置的发布时隙。时隙定义了首选的调度时间。

退货： 数组 { timeSlotHour, timeSlotMinute, weekDays } 哪里 weekDays 是 [0-6] （0=星期日）。

______________________________________________________________________

病毒模板

浏览从高绩效帖子中提取的病毒帖子模板库。每个模板都包括结构、使用说明和原始示例帖子及其参与度指标。

需要付费计划： 以下两种工具都需要一个有效的付费计划（用户拥有的计划、终身交易或拥有付费计划的工作区的会员资格）。免费计划用户将获得： _“访问病毒帖子模板需要付费计划”_.

list_viral_templates

列出带有过滤、自由文本搜索、排序和分页功能的病毒帖子模板。

退货： { templates, categories, totalCount, page, pageSize }.

每个模板：

list_viral_template_categories

列出所有可用的模板类别，并注明每个类别中的模板数量。在致电之前，作为发现步骤很有用 list_viral_templates 带着一个 category 过滤器。

参数： 无

退货： { categories: [{ category, templateCount }] }，按类别按字母顺序排列。

______________________________________________________________________

账户

get_subscription

获取您当前的计划、剩余职位限制和帐户配额。

退货： planType, planName, isFreePlan, remainingPosts, limits （最大团队数、最大成员数、最大账户数）。

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 → 附上促销回复

______________________________________________________________________

提示

MCP服务器包括内置的提示——可重复使用的模板，指导您的AI助手完成多步骤的工作流程。在 克劳德桌面版，通过键入来访问它们 / 在聊天中。在 克劳德代码，跑 claude prompts 列出它们。

weekly-report

生成一份包含参与度指标、热门帖子、追随者增长和建议的每周绩效报告。

论据：

例子： _“为我的Threads帐户运行周报提示”_

content-ideas

根据你表现最佳的内容和发布模式生成帖子创意。

论据：

例子： _“给我关于营销的内容想法”_

optimize-schedule

分析你的发帖模式，并建议本周的最佳发帖时间表。

论据：

例子： _“帮助我优化我的发布时间表”_

draft-review

在发布之前，请查看您当前的草稿并获得改进建议。

论据： 无

例子： _“审阅我的草稿，并告诉我如何改进”_

monthly-recap

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

论据：

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

______________________________________________________________________

API密钥管理

• 创建密钥： 设置>MCP>创建API密钥
• 视图键： 设置>MCP（显示前缀、创建日期、上次使用时间）
• 删除密钥： 单击任意按键旁边的垃圾图标
• 端点： GET/POST/DELETE /api/user/mcp-keys

密钥在存储之前用SHA-256进行散列。原始密钥在创建时只显示一次。

______________________________________________________________________

认证

MCP服务器支持两种身份验证方法。两者都使用 Authorization: Bearer 头球

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

服务器实现 MCP授权规范 使用OAuth 2.1和PKCE（S256）。像claude.ai这样支持OAuth的客户端会自动处理流。

OAuth端点：

它是如何工作的：

1. 客户端通过众所周知的元数据发现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）
• 运输： WebStandardStreamableHTTPServerTransport 从 @modelcontextprotocol/sdk
• 模式： 无状态（无会话管理）
• 认证： 带有PKCE（S256）或API密钥的OAuth 2.1通过 Authorization: Bearer 头球
• 未经身份验证的发现： initialize 和 tools/list 无需身份验证即可调用，因此MCP注册表（如Glama）可以检查可用工具
• 速率限制： 经过身份验证的请求的速率限制为每个IP每分钟60个请求。未经身份验证的发现请求限制为每个IP每分钟10个请求。
• 源代码： src/libs/mcp/ （服务器、身份验证、oauth、工具）， src/app/api/mcp/ （路由处理程序、OAuth端点）