PostMCP AI

PostMCP AI Model Context Protocol（MCP）服务

官方 PostMCP AI Model Context Protocol（MCP）服务。将社交媒体发布工作流直接接入 AI 助手、桌面应用、IDE 工作流以及 Claude Desktop、Claude.ai、Cursor 和 ChatGPT Custom GPTs 等 Web 环境。

支持的平台包括 LinkedIn、X (Twitter)、Facebook、Instagram、Threads、Bluesky 和 YouTube Shorts。

---

🚀 功能与能力

• 🤖 20 个内置工具：工作区、已连接的账号及其令牌状态、帖子队列、发布前检查、创建／安排／重新安排／发布／重试／删除、单篇帖子和单个个人资料的分析数据、媒体上传、图像生成和批量处理。
• 🖼️ 轮播和图片集：传入 mediaUrls，即可在 Instagram 和 Threads 上发布轮播内容，在 Facebook 和 LinkedIn 上发布多图帖子，或在 X 和 Bluesky 上发布四图图片集——一次调用，即可预先检查每个平台的数量上限。
• ⚡ 双传输模式：原生 Stdio 模式（适用于本地桌面应用和 IDE）以及 Streamable HTTP 模式（适用于 Web 服务、Claude.ai 和远程连接器）。
• 🔑 灵活的身份验证：自动从环境变量（POSTMCPAI_API_KEY）、URL 查询参数（?apikey=YOUR_KEY）或 HTTP 授权标头（x-api-key、Bearer token）检测 API 密钥。
• 🗂️ 支持多个工作区：API 密钥自带所属工作区，因此只提供密钥即可使用。若要操作其他工作区，每个工具都可接收可选的 workspaceId，也可以按连接（?projectId=...、x-project-id）或按进程（POSTMCPAI_PROJECT_ID）设置。
• 🤖 兼容 ChatGPT Actions：内置 OpenAPI 3.0 规范生成器（/openapi.json）和 REST 端点（/api/tools/:name），可集成 ChatGPT Custom GPT。
• 🔒 支持 PKCE 和 RFC 9728 的 OAuth：支持按用户授权、持久化加密授权、轮换令牌以及供 ChatGPT/Codex 使用的 DCR。需要在 OAUTH.md 中配置生产环境设置；同时仍支持 API 密钥客户端。
• 🧩 可安装的插件：支持账号接入、发布、安排发布和分析工作流。请参阅 PLUGIN.md 并运行 npm run package:plugin。

---

📁 仓库架构

mcp-server/
├── bin/
│   └── cli.js            # Executable CLI entry point (Stdio / HTTP mode runner)
├── src/
│   ├── config.js         # Centralized configuration & environment loader
│   ├── client.js         # Backend API client, API key & workspace extraction
│   ├── platforms.js      # Platform limits, credit pricing & post cost helper
│   ├── tools/
│   │   ├── definitions.js# MCP tool JSON schemas & parameter specifications
│   │   ├── handlers.js   # MCP tool execution handlers
│   │   └── index.js      # Tool definitions aggregator
│   ├── server.js         # MCP Server instance factory
│   ├── routes/
│   │   ├── oauth.js      # OAuth 2.0 & RFC 9728 discovery endpoints
│   │   ├── openapi.js    # OpenAPI 3.0 schema & ChatGPT REST endpoints
│   │   ├── mcpHttp.js    # MCP Streamable HTTP transport (/mcp)
│   │   └── health.js     # Health check & system metadata endpoints
│   ├── app.js            # Express application factory
│   └── index.js          # Main library entry point
├── index.js              # Executable wrapper script
├── package.json
└── README.md

---

⚙️ 环境配置

环境变量	说明	默认值
POSTMCPAI_API_KEY	必填。 从 PostMCP AI 控制面板获取的秘密 API 密钥。	None
POSTMCPAI_API_URL	后端 API 根地址。仅在使用可自托管或本地后端时设置。	https://api.postmcpai.com
POSTMCPAI_PROJECT_ID	可选。覆盖 API 密钥所绑定的工作区；工具调用中的 workspaceId 会进一步覆盖此设置。	签发该 API 密钥时所在的工作区
PORT	设置此项会启动 远程 Streamable HTTP 模式。	None（默认使用 Stdio 模式）

---

🛠️ MCP 工具参考

以下每个工具均可接收可选的 workspaceId（来自 list_workspaces），用于操作指定工作区。

读取

工具名称	描述	必填	可选
get_user_info	已通过身份验证的用户：套餐、积分余额、当前工作区和角色。	—	workspaceId
list_workspaces	用户所属的所有工作区，包括 ID、角色和已连接的平台。	—	—
get_connected_accounts	已连接的社交账号，以及用于指定目标账号的 profileId。	—	workspaceId
get_account_health	令牌已过期或即将过期、需要重新连接的账号。	—	workspaceId
get_profile_analytics	已连接账号的粉丝数、关注数、帖子数和来自其平台的浏览量。读取已存储的数据免费；使用 refresh 可立即读取平台数据，需消耗 1 个积分。	platform, profileId	refresh
list_posts	帖子队列，按最新优先排序，包含各账号的投递状态、分页和计数。	—	status, page, limit, all
get_post	单条帖子的完整信息：投递到哪些账号、公开 URL 和各账号的错误。	id	—
get_post_analytics	各账号的浏览量、点赞数、评论数、分享数、收藏数和点击量，以及原始平台指标。读取已存储的数据免费；使用 refresh 可立即读取平台数据，需消耗 1 个积分。	id	refresh

写入

工具名称	描述	必填	可选
preflight_post	试运行：检查字符数限制、未连接的账号、缺少的媒体、轮播上限和积分成本。不会发布任何内容。	content	targetAccounts, platforms, mediaUrl, mediaUrls
create_post	向指定账号创建草稿、安排发布或立即发布帖子。每个账号会创建一条独立的帖子，并分配自己的 ID。多个 mediaUrls 会作为轮播发布。	content	targetAccounts, variants, platforms, publishImmediately, scheduleDate, scheduleTime, timezone, mediaUrl, mediaUrls, youtube
publish_post_now	立即发布现有帖子；也可重试失败的帖子，并跳过已投递到的账号。	id	—
update_post	更新内容、目标账号、发布时间、媒体或状态。mediaUrls 会替换整个附件集合。	id	content, targetAccounts, platforms, scheduleDate, scheduleTime, timezone, mediaUrl, mediaUrls, youtube, status
reschedule_post	将帖子移至新的时间段，同时保留文案和目标账号。重新启用失败的帖子和草稿。	id, scheduleDate, scheduleTime	timezone
reset_stuck_post	释放卡在发布过程中的帖子，以便重试。已投递账号的状态保持不变。	id	force
delete_post	取消并删除已安排发布或失败的帖子。	id	—
generate_image	生成帖子图片，并返回可用于 mediaUrl 的托管 URL。需消耗 20 个积分；仅限付费套餐。	prompt	styleImageUrl
create_media_upload_url	授权直接上传图片或视频；返回带签名的 PUT URL 和将来的公开 URL。	fileName, contentType, fileSize	workspaceId
complete_media_upload	将成功上传的文件登记到媒体库，并返回 mediaUrl。	url, key, fileName, contentType, fileSize	workspaceId
import_media_from_url	将公开图片或视频复制到存储空间和媒体库；返回 mediaUrl。	url	workspaceId

媒体上传

对于本地文件，MCP 客户端需要具备 HTTP 上传能力：

1. 使用 fileName、contentType（MIME 类型）和 fileSize（字节数）调用 create_media_upload_url。例如：{ "fileName": "launch.png", "contentType": "image/png", "fileSize": 245760 }。
2. 使用返回的 headers，将原始文件字节 PUT 到返回的 uploadUrl。不要将 PostMCP API 密钥发送到存储服务。URL 会在 expiresIn 秒后过期（通常为 900 秒）；如果过期，请重新请求。仅创建 URL 并不会上传文件。
3. PUT 成功后，使用返回的 publicUrl 作为 url，并传入返回的 key 以及相同的文件元数据，调用 complete_media_upload。两个工具都使用相同的 workspaceId。此操作会登记文件；不会传输或验证文件字节。
4. 在 create_post 或 update_post 中使用返回的 mediaUrl，或将多个 URL 收集到 mediaUrls 中以创建轮播。

对于已有的公开文件，使用 { "url": "https://example.com/launch.png" } 调用 import_media_from_url。后端会在一次调用中下载文件并返回存储后的 mediaUrl。该 URL 必须无需身份验证即可直接提供文件；后端会拒绝指向私有网络的 URL。

存储支持 PNG、JPEG、GIF、WebP、AVIF、HEIC、MP4、MOV、WebM 和 M4V；图片上限为 25 MiB，视频上限为 512 MiB。各社交平台的发布要求可能更严格；发布前请使用 preflight_post。文件字节和 base64 不会通过 MCP JSON 请求传输。如果存储成功后媒体库登记失败，结果会包含 librarySaved: false 和一条警告，同时保留可用的 mediaUrl。

批处理

工具名称	说明	必需	可选
multicall	在一个请求中按顺序运行上述最多 20 个工具。执行任何操作前会先验证工具名称，因此拼写错误不会导致批次只写入一部分。不能嵌套。	calls	stopOnError、workspaceId

{
  "calls": [
    { "id": "img", "tool": "generate_image", "arguments": { "prompt": "launch banner" } },
    {
      "tool": "create_post",
      "arguments": {
        "content": "We shipped it 🚀",
        "targetAccounts": [
          { "platform": "linkedin", "profileId": "lin_7741903" },
          { "platform": "twitter", "profileId": "tw_1293847", "content": "We shipped it 🚀" }
        ],
        "scheduleDate": "2026-09-01",
        "scheduleTime": "10:00",
        "timezone": "Asia/Kolkata"
      }
    }
  ],
  "stopOnError": true
}

回复会为每次调用返回一条记录——{ id, tool, ok, result } 或 { id, tool, ok: false, error }——以及计数；如果某次失败导致批次停止，还会包含被跳过的调用。

轮播

mediaUrls 是有序的附件集合。一个 URL 会作为普通媒体帖发布；两个或更多 URL 会在 YouTube 以外的所有网络平台上发布为多媒体帖，并将第一个 URL 作为封面：

平台	每帖项目数	多个项目组成的集合中可包含视频？	发布形式
Instagram	2–10	可以	轮播
Threads	2–20	可以	轮播
Facebook	最多 10 个	不可以	多图帖
LinkedIn	最多 20 个	不可以	多图帖
X / Twitter	最多 4 个	不可以	单条推文中的图库
Bluesky	最多 4 个	不可以	单条帖文中的图库
YouTube	1 个	—	每次上传发布一个视频

{
  "content": "Five things we learned shipping v2 👉",
  "targetAccounts": [
    { "platform": "instagram", "profileId": "17841400000000" },
    { "platform": "threads", "profileId": "9988776655" },
    { "platform": "twitter", "profileId": "tw_1293847",
      "mediaUrls": ["https://cdn.example.com/v2/1.png", "https://cdn.example.com/v2/2.png", "https://cdn.example.com/v2/3.png", "https://cdn.example.com/v2/4.png"] }
  ],
  "mediaUrls": [
    "https://cdn.example.com/v2/1.png",
    "https://cdn.example.com/v2/2.png",
    "https://cdn.example.com/v2/3.png",
    "https://cdn.example.com/v2/4.png",
    "https://cdn.example.com/v2/5.png"
  ],
  "scheduleDate": "2026-09-01",
  "scheduleTime": "10:00",
  "timezone": "Asia/Kolkata"
}

• 只有 Instagram 和 Threads 支持在轮播中混合视频；其他平台上的多个项目必须全是图片，视频必须单独发布。
• 如果目标平台不接受某个媒体集合，create_post 会在消耗任何额度之前拒绝该集合，并指出对应的账号和规则。使用相同的 mediaUrls 调用 preflight_post 会报告同样的信息，并附带 mediaSetLimits 映射；因此，如果要将一个轮播发布到多个网络，请先检查。
• 账号可以在其 targetAccounts 条目中单独设置 mediaUrls（也可以在 variants 中设为 { "twitter": { "mediaUrls": [...] } }），以替换共享集合——这样就能为 X 和 Bluesky 提供从较长轮播中截取的四页版本。
• 写入时，每张幻灯片都会复制到 PostMCP 自己的存储中，与单个附件的处理方式相同，因此即使托管链接之后过期，也不会影响已安排的帖子。如果发布时有一张幻灯片失败，该账号的帖子就会失败，而不会发布缩短后的轮播；publish_post_now 会重试。
• 使用 mediaUrls 调用 update_post 会替换整个集合（添加、移除或重新排列幻灯片）；空数组会移除所有媒体。list_posts / get_post 返回的每个帖子都会包含 mediaUrls 和 mediaUrl。

给客户端的说明

• 指定目标个人资料，而非平台。 targetAccounts 只会向指定的个人资料发送；platforms 则会向每个平台上所有已连接的个人资料发送。
• 每个个人资料对应一条帖子。 create_post 会为每个目标个人资料单独存储一条帖子，因此可以分别编辑、重试或取消。可通过 targetAccounts[].content 或 variants 映射为各个人资料提供不同文案。
• 涉及具体时刻时，务必传入 timezone。 后端默认使用 UTC，因此未指定时区而将帖子安排在 IST 时间 9:00 发布时，实际会在 IST 时间 14:30 发布。
• 积分按发布到的个人资料数量扣除（X/Twitter 每个需 5 积分，其他平台每个需 1 积分）；如果文案包含链接，还会一次性额外扣除 50 积分。preflight_post 会在你确认前报告这些费用。
• 分析数据只会按需读取，不会在后台读取。 list_posts 和 get_connected_accounts 会返回上次读取时存储的数据，不收费。对于 get_post_analytics（一条帖子所发布到的所有网络）和 get_profile_analytics（一个已连接的个人资料：关注者、帖子、浏览量），传入 refresh: true 会立即从网络读取数据，每次需 1 积分；不传则免费返回已存储的数据。engagements 是所有网络上的点赞数、评论数和分享数之和，因此可以跨平台比较。null 表示网络不报告该指标（Bluesky 不提供浏览量）；error 中提到 reconnect 表示该账号的创建时间早于洞察权限，所有者必须重新连接账号；unavailable: true 表示该网络不会针对这类帖子提供数据（LinkedIn 个人资料）。

---

💻 客户端集成指南

1. Claude Desktop App（Stdio 模式）

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

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

{
  "mcpServers": {
    "postmcpai": {
      "command": "npx",
      "args": ["-y", "@postmcpai/server"],
      "env": {
        "POSTMCPAI_API_KEY": "pmcp_sec_your_secret_api_key_here"
      }
    }
  }
}

---

2. Cursor IDE

1. 打开 Cursor 设置 -> 功能 -> MCP。
2. 点击 + 添加新的 MCP 服务。
3. 填写详细信息：
   • 名称：postmcpai
   • 类型：command
   • 命令：npx -y @postmcpai/server
4. 在 环境变量 下添加：
   • POSTMCPAI_API_KEY = pmcp_sec_your_secret_api_key_here
5. 点击 保存。

---

3. Claude.ai 和远程 Web 连接器（Streamable HTTP / SSE 模式）

将此服务托管在任意云服务上（Render、Railway、Fly.io、Vercel），或使用 ngrok 为本地机器建立隧道。

以 HTTP 模式启动：

export PORT=3000
# Each remote caller supplies its own API key or OAuth token.

npm run start:sse

连接到 Claude.ai：

1. 提供附带 API 密钥的公开 MCP URL： https://your-hosted-domain.com/mcp?apikey=pmcp_sec_your_secret_api_key_here
2. Claude.ai 会通过 /mcp 发现工具功能，并自动完成身份验证。
3. 只需提供此 URL：密钥绑定到签发它的工作区，因此工具会直接作用于该工作区，无需额外说明。若要将同一密钥指向其他工作区，请追加 &projectId=YOUR_WORKSPACE_ID（或发送 x-project-id 标头）；各工具调用仍可通过 workspaceId 覆盖上述任一设置。

---

4. ChatGPT 自定义 GPT（REST Actions）

1. 配置自定义 GPT Action 时，指定你的服务 URL（例如 https://your-hosted-domain.com）。
2. 直接从以下地址导入 OpenAPI 架构： https://your-hosted-domain.com/openapi.json
3. 将身份验证设为 API Key（Bearer Authorization 或自定义 x-api-key）。这是 GPT Actions 集成，并非面向单个客户的 OAuth 插件。若需使用该插件，请参阅 OAUTH.md。

---

5. 以编程方式使用 Node.js 库

你也可以在自己的 Node.js 后端中将 @postmcpai/server 用作库：

import { createServer, createExpressApp, makeBackendRequest } from "@postmcpai/server";

// Create a standalone MCP Server instance
const mcpServer = createServer(() => process.env.POSTMCPAI_API_KEY);

// Or create an Express app with all remote routes attached
const app = createExpressApp();
app.listen(3000);

---

🧪 本地测试与开发

# Clone the repository
git clone https://github.com/postmcp/postmcp-mcp-server.git
cd postmcp-mcp-server

# Install dependencies
npm install

# Start in Stdio Mode
npm start

# Start in HTTP Mode with hot reload
npm run dev

---

📄 许可证

基于 MIT License 发布。版权所有 © 2026 PostMCP AI。