Bulkpublish

BulkPublish MCP 服务

一个 Model Context Protocol 服务，让 Claude 和其他 AI 助手能够与 BulkPublish 社交媒体发布 API 交互。

功能

此 MCP 服务将 BulkPublish API 操作作为工具提供，供 AI 助手直接调用。你可以用自然对话让 Claude 安排帖子、查看分析数据、上传媒体、管理标签等。

安装

选项 1：npx（推荐）

npx @bulkpublish/mcp-server

选项 2：全局安装

npm install -g @bulkpublish/mcp-server
bulkpublish-mcp

选项 3：从源代码安装

git clone https://github.com/azeemkafridi/bulkpublish-api.git
cd bulkpublish-api/mcp-server
npm install
npm run build
node dist/index.js

需要 Node ≥ 20.19。npm run build 会先通过 Vite 打包 composer UI（build:ui），然后使用 tsc 编译服务。

配置

将 API 密钥设置为环境变量：

export BULKPUBLISH_API_KEY=bp_your_api_key_here

在 app.bulkpublish.com/developer 获取 API 密钥。

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bulkpublish": {
      "command": "npx",
      "args": ["-y", "@bulkpublish/mcp-server"],
      "env": {
        "BULKPUBLISH_API_KEY": "bp_your_api_key_here"
      }
    }
  }
}

如果你从源代码安装：

{
  "mcpServers": {
    "bulkpublish": {
      "command": "node",
      "args": ["/absolute/path/to/bulkpublish-api/mcp-server/dist/index.js"],
      "env": {
        "BULKPUBLISH_API_KEY": "bp_your_api_key_here"
      }
    }
  }
}

Claude Code

将 MCP 服务添加到 Claude Code 配置中：

claude mcp add bulkpublish -- npx -y @bulkpublish/mcp-server

在 Shell 配置文件或 .env 文件中设置环境变量：

export BULKPUBLISH_API_KEY=bp_your_api_key_here

远程／托管服务（HTTP）

上面的 npx／stdio 配置会在本地运行服务。无法启动本地进程的 Web 客户端——claude.ai 自定义连接器和 Smithery 的网关——则连接到托管的 HTTP 端点。除了 stdio 可执行文件外，此服务还提供 Streamable HTTP 传输方式（dist/http.js，使用 npm run start:http 运行）：

端点	用途
POST /mcp	MCP Streamable HTTP（无状态）
GET /.well-known/mcp/server-card.json	静态元数据，供注册表跳过扫描
GET /health	存活检查

此服务支持多租户——进程不持有任何 API 密钥。每个调用方都通过连接 URL（?key=bp_…）、Smithery ?config= 数据块或 Authorization: Bearer bp_…／X-BulkPublish-Key 请求头，在每次请求中提供自己的 bp_… 密钥。initialize、tools/list 和 resources/* 无需密钥（因此扫描和工具发现都能正常进行）；不带密钥的 tools/call 请求会返回 401。

项目包含 Dockerfile：

docker build -t bulkpublish-mcp . && docker run -p 8080:8080 bulkpublish-mcp

部署后，将其添加到 claude.ai → Settings → Connectors → Add custom connector，并使用 https://<host>/mcp?key=bp_…；或者将 https://<host>/mcp URL 发布到 Smithery。

工具配置

此服务提供三种工具配置，可通过 BULKPUBLISH_TOOL_PROFILE 选择：

配置	工具	默认用于
core	20 个——频道、帖子、媒体、分析和交互式面板	托管 HTTP 服务（dist/http.js），Claude 和 ChatGPT 目录中列出的就是该服务
inbox	27 个——包含 core 中的全部工具，另加收件箱和评论工具：list_conversations、get_conversation、reply_to_conversation、update_conversation、list_post_comments、reply_to_comment、moderate_comment	在托管部署上选择启用（BULKPUBLISH_TOOL_PROFILE=inbox）。其中的 core 工具与 core 配置中的完全相同
full	所有工具（包括收件箱和评论工具、标签、话题标签组、模板、日历备注、审核链接、客户端连接链接、定期计划、频道集、RSS 源、分块上传、配额）	本地 stdio 服务（npx @bulkpublish/mcp-server）

在托管部署上设置 BULKPUBLISH_TOOL_PROFILE=full 以开放所有工具，或在本地设置为 core 以保持工具列表精简。面板的按钮会调用 create_post、publish_post、retry_post、update_post、delete_post、list_channels、list_media、get_post、create_media_upload 和 finalize_media_upload，因此这些工具都包含在 core 中。

每个工具都包含一个 title，以及明确的 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint 布尔值；npm run check:annotations 会验证每种配置中的这些值（添加 --table 可打印目录提交中使用的逐工具理由表）。

可用工具

标有 ★ 的工具属于 core 配置（参见工具配置）；标有 ✉ 的工具属于 inbox 配置（同时包含所有 ★ 工具）；其余工具需要 full 配置。

工具	描述
帖子
create_post ★	创建帖子，并可选择安排发布时间（通过 postTypeOverrides 支持短视频、快拍、轮播和串帖）
compose_post ★	打开交互式编辑器 UI（MCP Apps）以起草或安排帖子；通过 create_post 提交
update_post ★	更新草稿或已安排的帖子
get_post ★	获取单条帖子的完整详情
list_posts ★	按状态、搜索词和日期范围等筛选条件列出帖子
delete_post ★	删除帖子
publish_post ★	立即发布草稿帖子
retry_post ★	重试发布失败的帖子
approve_post	批准待团队审核的帖子（适用于具有 post:approve 权限的角色）
reject_post	拒绝待审核的帖子，使其退回草稿状态；可选择提供原因
get_post_metrics ★	获取互动指标（展示次数、赞、评论、分享）。每个平台条目都包含 supportedMetrics；不在该列表中的键表示存储值为 0，而非实际测量值
publish_story	将内容作为快拍发布到 Facebook 或 Instagram
bulk_posts	批量删除或重试多个帖子
get_queue_slot ★	获取频道的下一个最佳时间段
频道
list_channels ★	列出所有已连接的社交媒体频道
get_channel_health	检查频道令牌的健康状态
get_channel_options	获取平台专属选项（看板、播放列表）
search_mentions	搜索可用于 @提及的用户（X、Bluesky、Mastodon、LinkedIn Pages——LinkedIn 结果包含匹配所用的 vanityName 标识）
频道组
list_channel_sets	列出已保存的频道组，便于一键指定多个频道
create_channel_set	保存一个命名频道组（每个组织最多 50 个，且名称在组织内必须唯一）
update_channel_set	重命名频道组或更改其频道
delete_channel_set	删除频道组
RSS 自动发布
list_rss_feeds	列出每 15 分钟轮询一次的 RSS/Atom 订阅源（新条目会成为帖子）
create_rss_feed	添加订阅源（每个组织最多 20 个）；mode = draft（默认，新条目会成为草稿）或 publish（自动发布）；可选的 fieldMapping 用于控制条目的呈现方式（文案模板、媒体选择、截断方式、各频道覆盖设置）
update_rss_feed	更改、暂停订阅源或更改其指向（更改 feedUrl 会重新建立基准，不会涌入积压内容）
delete_rss_feed	停止并移除订阅源
媒体
upload_media ★	从 URL（或 stdio 服务上的本地路径）上传媒体文件
get_media	按 ID 获取媒体文件
list_media ★	列出已上传的媒体文件
delete_media	删除媒体文件
create_media_upload ★	预留用于直接浏览器上传的预签名 R2 URL（供编辑器使用）
finalize_media_upload ★	浏览器 PUT 上传完成后，将已上传对象登记为媒体文件（供编辑器使用）
create_multipart_upload	为大型媒体文件启动分块上传（视频最大 1GB）——为固定的 10MB 分块生成预签名 URL
complete_multipart_upload	组装已上传的分块（每块包含 partNumber + ETag），并登记媒体文件
abort_multipart_upload	取消正在进行的分块上传，并释放已存储的分块
标签
create_label	创建新标签
list_labels	列出所有标签
update_label	更新标签名称或颜色
delete_label	删除标签
分析
get_analytics ★	获取指定日期范围的分析摘要
计划
list_schedules	列出定期计划
create_schedule	创建定期计划
update_schedule	更新计划
delete_schedule	删除计划
收件箱和评论
list_conversations ✉	列出私信、评价和评论串，按最新活动时间排序，并支持筛选和分页（Pro 和 Business 套餐）
get_conversation ✉	读取一段对话中的消息，按时间从早到晚排列；不会将其标记为已读
reply_to_conversation ✉	立即在平台上向对方发送回复；发送后无法撤回
update_conversation ✉	将对话标记为已读或未读、归档或重新打开、稍后提醒或分配对话；不会发送任何内容
list_post_comments ✉	按频道列出已发布帖子上的评论和回应，并提供回复及管理工具所需的 ID
reply_to_comment ✉	立即以发布该帖子的频道身份，公开回复评论
moderate_comment ✉	在平台上赞、取消赞、隐藏、取消隐藏或删除评论（删除后无法恢复）
账户
get_quota_usage	查看当前账户用量（当 BULKPUBLISH_HIDE_BILLING=1 时隐藏）
交互式 UI（MCP Apps）
compose_post ★	打开交互式帖子编辑器（上文也有列出）
view_analytics ★	打开交互式分析仪表板
view_posts ★	打开交互式帖子列表
view_channels ★	打开交互式频道视图
view_media ★	打开交互式媒体库
view_quota	打开交互式账户用量视图（当 BULKPUBLISH_HIDE_BILLING=1 时隐藏）

交互式 UI（MCP Apps）

在支持 MCP Apps 的宿主中——Claude、ChatGPT、VS Code、Goose、Postman 和 Smithery playground——compose_post 工具会在对话中内嵌打开一个交互式编辑器：选择渠道、撰写内容、按需设置发布时间，然后提交。提交时，它会通过宿主桥接调用 create_post，因此沙盒 iframe 不会持有你的 API 密钥。不支持 MCP Apps 的宿主只会收到纯文本摘要，因此不会造成任何问题。

多个工具会呈现 UI：compose_post（编辑器）、view_analytics、view_posts、view_channels、view_media 和 view_quota。每个工具都是 src/ui/<name>/ 下的独立组件，使用 Vite 打包为单个 HTML 文件（每个组件单独进行一次单输入构建——参见 scripts/build-ui.mjs），并通过 src/ui/widgets.generated.ts 内嵌到服务中。这些组件共用 BulkPublish Web 应用的设计令牌（src/ui/tokens.css），因此外观保持一致。View 会从触发工具的 structuredContent 获取数据，也可以通过宿主桥接调用其他工具——因此沙盒 iframe 不会持有你的 API 密钥。不支持 MCP Apps 的宿主只会收到纯文本摘要。

对话示例

以下是在 Claude 中使用 BulkPublish 工具的示例：

你： 安排明天上午 9 点（EST）发布一条帖子，内容为“很高兴宣布我们的新功能！快来 example.com 看看”，并发布到我连接的所有渠道。

Claude： 我先查看你连接的渠道。

[调用 list_channels]

你有 3 个活跃渠道：

• X/Twitter：@yourcompany（ID：1）
• LinkedIn：Your Company Page（ID：2）
• Instagram：@yourcompany（ID：3）

现在，我会将这条帖子安排在明天东部时间上午 9:00 发布。

[使用 content、channels、scheduledAt: "2025-01-16T14:00:00Z"、timezone: "America/New_York"、status: "scheduled" 调用 create_post]

完成！你的帖子已安排发布：

• 帖子 ID：42
• 状态：scheduled
• 计划发布时间：2025 年 1 月 16 日上午 9:00（EST）
• 渠道：X/Twitter、LinkedIn、Instagram

---

你： 我这个月发布的帖子表现如何？

Claude： [使用 from: "2025-01-01"、to: "2025-01-31" 调用 get_analytics]

以下是你的 1 月分析摘要：

• 帖子总数：28
• 已发布：25
• 失败：1
• 已安排（待处理）：2
• 按平台统计：X/Twitter（25 条帖子，24 条已发布）、LinkedIn（20 条帖子，19 条已发布）、Instagram（15 条帖子，全部已发布）
• 最佳日期：1 月 12 日，共发布 5 条帖子

---

你： 上传这张图片，并用它创建一条草稿帖子：https://example.com/product-launch.png

Claude： [使用 url 调用 upload_media]

图片上传成功（ID：15，1200x630px，245KB）。

[使用 content 和 mediaFileIds 调用 create_post]

已创建草稿帖子（ID：43），并附上产品发布图片。准备好后，你可以查看并发布。

环境变量

变量	必需	默认值	说明
BULKPUBLISH_API_KEY	是	—	你的 API 密钥（以 bp_ 开头）
BULKPUBLISH_BASE_URL	否	https://app.bulkpublish.com	API 基础 URL（用于自托管实例）
BULKPUBLISH_TOOL_PROFILE	否	full (stdio) / core (hosted HTTP)	core、inbox 或 full——参见工具配置
BULKPUBLISH_HIDE_BILLING	否	—	1 会移除 get_quota_usage 和 view_quota（仅适用于 full；core 不包含这些工具）

许可证

MIT