PlanPost

planpost-mcp

适用于 PlanPost 的 MCP（Model Context Protocol）服务。PlanPost 是一款具备收入归因功能的 Agent 社交媒体排程工具。它可以让 Claude、ChatGPT、Cursor、Gemini CLI 和其他 AI Agent 连接你的 PlanPost 账户，安排社交媒体帖子、创建视频和轮播图、管理内容来源，以及读取分析和收入数据。

快速开始

简便方式：登录

将 https://mcp.planpo.st/mcp 添加到你的 Agent 中，作为远程 MCP 服务（在 Claude 和 ChatGPT 中称为“连接器”），并将身份验证字段留空。Agent 首次使用时，会在 planpo.st 上打开浏览器：登录、查看 Agent 可以执行的操作，并选择是否让帖子先等待你的批准。无需创建或粘贴密钥。

claude mcp add --transport http planpost https://mcp.planpo.st/mcp

{ "mcpServers": { "planpost": { "url": "https://mcp.planpo.st/mcp" } } }

已连接的 Agent 会列在 Settings → API Keys → Connected apps 下，你可以随时移除。它们使用与 API 密钥相同的权限和每月调用额度。

该仓库还提供了可直接使用的套件：Claude Code 插件（.claude-plugin/）、Cursor 插件（.cursor-plugin/）、Gemini CLI 扩展（gemini-extension.json）和 Agent 技能：

npx skills add lukBB/planpost-mcp --skill planpost
gemini extensions install https://github.com/lukBB/planpost-mcp
claude plugin marketplace add lukBB/planpost-mcp && claude plugin install planpost@planpost-plugins

本节其余内容介绍 API 密钥方式：可用于不支持 OAuth 的客户端、CI，或者需要将密钥权限限制为少数几项的情况。

1. 获取 API 密钥

在 PlanPost 控制面板中，前往 Settings → API Keys → Create Key，选择所需权限（见下表）。密钥（pk_live_…）只会显示一次，请复制保存。

所有付费套餐均包含 API/MCP 访问权限：Creator：每月 1,000 次调用；Pro：每月 10,000 次调用。密钥的权限范围有限：仅有 posts:read 权限的密钥无法发布帖子。

2. 将服务添加到你的 Agent

有两种连接方式。默认使用托管方式：将客户端指向 https://mcp.planpo.st/mcp，无需安装任何内容，密钥通过标头传递。 本地方式使用 npx 在你的机器上运行同一服务，密钥不会离开本机。两种方式都提供相同的 49 个工具。

请在各处将 pk_live_xxx 替换为你的密钥。

Claude Code

claude mcp add --transport http planpost https://mcp.planpo.st/mcp \
  --header "Authorization: Bearer pk_live_xxx"

本地备用方式：

claude mcp add planpost -e PLANPOST_API_KEY=pk_live_xxx -- npx -y planpost-mcp

之后运行 claude mcp list，确认连接成功。

Claude Desktop

托管方式：Settings → Connectors → Add custom connector。将名称设为 PlanPost，URL 设为 https://mcp.planpo.st/mcp，然后添加标头 Authorization: Bearer pk_live_xxx。

本地备用方式：在 claude_desktop_config.json 中配置（macOS： ~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\），然后 重启应用：

{
  "mcpServers": {
    "planpost": {
      "command": "npx",
      "args": ["-y", "planpost-mcp"],
      "env": { "PLANPOST_API_KEY": "pk_live_xxx" }
    }
  }
}

Cursor（~/.cursor/mcp.json，或每个项目中的 .cursor/mcp.json）

{
  "mcpServers": {
    "planpost": {
      "url": "https://mcp.planpo.st/mcp",
      "headers": { "Authorization": "Bearer pk_live_xxx" }
    }
  }
}

本地备用方式：将条目替换为 { "command": "npx", "args": ["-y", "planpost-mcp"], "env": { "PLANPOST_API_KEY": "pk_live_xxx" } }。 项目级的 .cursor/mcp.json 会随仓库一同提交，因此建议使用托管方式，并避免将密钥放入文件。

OpenAI Codex CLI（~/.codex/config.toml）

[mcp_servers.planpost]
url = "https://mcp.planpo.st/mcp"
bearer_token_env_var = "PLANPOST_API_KEY"

在 shell 中导出 PLANPOST_API_KEY；Codex 会从环境中读取令牌，而不是从文件读取。codex mcp add 可通过交互方式完成相同操作。

本地备用方式：

[mcp_servers.planpost]
command = "npx"
args = ["-y", "planpost-mcp"]

[mcp_servers.planpost.env]
PLANPOST_API_KEY = "pk_live_xxx"

Gemini CLI（~/.gemini/settings.json，或每个项目中的 .gemini/settings.json）

{
  "mcpServers": {
    "planpost": {
      "httpUrl": "https://mcp.planpo.st/mcp",
      "headers": { "Authorization": "Bearer pk_live_xxx" },
      "timeout": 10000
    }
  }
}

Gemini CLI 使用 httpUrl 进行流式 HTTP 连接，而不是 url；使用错误的键不会有任何提示。本地备用方式：使用与 Cursor 相同的 command/args/env 条目。

**任何其他 MCP 客户端：**连接到 https://mcp.planpo.st/mcp（流式 HTTP，每个请求都需携带 Authorization: Bearer pk_live_xxx），或通过 stdio 运行 npx -y planpost-mcp，并设置 PLANPOST_API_KEY。各客户端的分步指南及截图见：planpo.st/docs/agents。

自托管 HTTP 端点

mcp.planpo.st 是同一个带 --http 运行的软件包。要运行自己的实例：

npx -y planpost-mcp --http --port 3020     # exposes POST /mcp (+ /health)

在反向代理后运行时，请绑定到环回地址，以免端口可被直接访问：

HOST=127.0.0.1 npx -y planpost-mcp --http --port 3020

该传输方式是无状态的（可流式传输的 HTTP）；每个请求都会读取凭据，并将凭据限定在该请求内，因此一个托管实例即可安全地服务多位用户。生产环境中，请将其置于 HTTPS 后。--host / HOST 默认值为 0.0.0.0，因此容器和局域网环境无需额外标志即可使用。

自托管端点开箱即支持 API 密钥（Authorization: Bearer pk_...）。设置以下三个变量即可启用 OAuth 登录，但需要使用运行授权服务器（/oauth/*）的 PlanPost API：

变量	描述
PLANPOST_MCP_PUBLIC_URL	此端点的公开 URL，例如 https://mcp.example.com/mcp。令牌仅针对这个确切的 URL 签发。
PLANPOST_MCP_SERVICE_SECRET	与 API 共享的 32 个或更多随机字符（API 端的 MCP_SERVICE_SECRET）。
PLANPOST_OAUTH_ISSUER	授权服务器的源站。默认为 PLANPOST_API_URL。
OPENAI_APPS_CHALLENGE	可选。在 /.well-known/openai-apps-challenge 提供令牌，用于验证 ChatGPT 目录域名。

设置这些变量后，服务端将遵循 MCP 授权规范：提供 /.well-known/oauth-protected-resource，对未认证的请求返回 401 和 WWW-Authenticate: Bearer resource_metadata="…" 挑战， 通过内省验证访问令牌，检查令牌是否针对该端点签发，并且绝不会将其转发到上游。

3. 与它交流

“将这篇帖子安排到我的 Polish Pages 群组，明天 9:00 发布：…”

“将这段客户评价制作成引述视频，并以短视频形式发布。”

“获取我的 WordPress 博客的最新帖子，并根据最新帖子起草一个 LinkedIn 轮播帖。”

“过去 30 天，我的帖子带来了多少收入？”

环境变量

变量	必需	描述
PLANPOST_API_KEY	仅 stdio	来自 Settings → API Keys 的 API 密钥（pk_live_…）。使用 --http 时无需设置，每个请求都会携带自己的凭据。
PLANPOST_API_URL	—	API 基础 URL（默认 https://api.planpo.st）

工具

共 49 个工具，按下方分组。权限列表示工具所需的作用域，无论凭据来自 API 密钥还是 OAuth 登录；缺少所需作用域的凭据会返回明确错误，而不会静默失败。每个工具都带有 MCP 注解（标题以及只读、破坏性和开放世界提示），以便客户端了解哪些调用需要确认。

帖子与发布

工具	所需权限	描述
list_posts	posts:read	列出帖子，按状态／平台筛选
get_post	posts:read	获取单条帖子
create_post	posts:write	创建草稿或定时发布的帖子（按平台设置内容／选项／媒体、UTM 覆盖项和时区）
update_post	posts:write	更新草稿或定时发布的帖子
delete_post	posts:write	删除帖子
publish_post	posts:write	立即发布
retry_failed	posts:write	重新排队处理因临时原因而失败的平台；绝不会重复发布已成功发布的内容
get_delivery_report	posts:read	每日早间检查：近期失败或部分失败的帖子及各平台的错误和修复方法、不健康的连接，以及延迟处理的审批
preview_post	posts:read	准确显示各平台将收到的内容（应用覆盖项后的文本、附件、警告）
bulk_create_posts	posts:write	根据一个清单创建整组营销活动帖子
list_campaigns	posts:read	查看正在使用的营销活动标签，以及按状态和平台统计的帖子数量
delete_posts	posts:write	批量删除符合筛选条件的帖子（必须提供筛选条件）
list_media	media:read	查看已上传的媒体，以便重复使用素材，而无需重新上传
upload_media	media:write	获取用于上传图片／视频的预签名 URL
repurpose_content	repurpose:write	将改编后的内容保存为草稿帖子

账号

工具	所需权限	描述
list_connections	connections:read	已连接的社交账号
list_account_groups	groups:read	已命名的账号组（例如 “Polish Pages”）
get_account_group	groups:read	按 ID／名称／默认组解析账号组 → 连接 ID
create_account_group	groups:write	创建包含多个连接的命名账号组
update_account_group	groups:write	重命名、更改颜色、设为默认组，或替换账号组中的连接
delete_account_group	groups:write	删除账号组（账号仍保持连接）
add_connections_to_group	groups:write	将连接添加到账号组
remove_connections_from_group	groups:write	从账号组中移除连接
get_connection_link	connections:read	用户在浏览器中打开以连接新社交账号的链接（OAuth 需要人工操作）

连接新的社交账号需要在浏览器中进行 OAuth：get_connection_link 会将链接交给用户，账号连接后，Agent 即可将其设为目标账号。

审批

工具	所需权限	描述
submit_for_approval	approvals:write	将帖子发送给人工审核员（API 密钥受审批限制时必须使用）
list_pending_approvals	approvals:read	查看等待审核的帖子及处理结果
get_approval_status	approvals:read	查看某次提交的待处理／已批准／已拒绝／要求修改状态

排期

工具	所需权限	描述
get_best_times	schedule:read	根据账号的互动历史，获取各平台的最佳发帖时间
suggest_schedule	schedule:read	在指定日期范围内按最佳时间分配 N 条帖子；返回具体时间戳
get_posting_schedule	schedule:read	查看每周队列时段，包括全局设置和各账号组的覆盖设置
set_posting_schedule	schedule:write	替换全局排期或某个账号组的每周队列时段（Pro）

视频和轮播图

工具	所需权限	描述
list_video_templates	videos:read	浏览视频模板及其可编辑字段
create_video	videos:write	使用模板提交渲染任务
get_video_status	videos:read	轮询渲染状态；渲染完成后会返回下载 URL
generate_carousel	carousels:write	将长篇内容拆分为轮播幻灯片文案
list_carousel_styles	carousels:read	模板系列、40 种配色库、格式和字体搭配
render_carousel	carousels:write	将幻灯片渲染为媒体库中的品牌 PNG 图片
get_carousel_render	carousels:read	轮询渲染状态；渲染完成后会返回可直接发布的媒体资源
list_brand_kits	brand-kits:read	已保存的品牌套件（配色、字体、徽标、账号名），供 render_carousel 使用
generate_image	images:write	使用 AI 为帖子生成图片（消耗 1 个 AI 点数）；将 URL 传给 create_post

内容源

工具	所需权限	描述
list_content_sources	content-sources:read	列出 WordPress/RSS 来源
add_content_source	content-sources:write	连接 WordPress 网站或 RSS 订阅源
delete_content_source	content-sources:write	移除来源
fetch_source_content	content-sources:write	立即导入最新内容
list_imported_content	content-sources:read	列出已导入、可供改编的内容

分析和收入

工具	所需权限	描述
get_analytics	analytics:read	帖子表现（展示量、点赞、评论、分享）
get_revenue_overview	revenue:read	收入总额和趋势；也可选择查看近期交易和 Stripe/RevenueCat MRR

API 仅支持读取收入数据；Stripe/RevenueCat/Shopify 需在控制面板中连接（Settings → Revenue）。

品牌语气（Pro）

工具	所需权限	描述
get_brand_voices	brand-voice:read	根据用户内容分析得出的语气档案
get_brand_voice_prompt	brand-voice:read	可直接使用的语气系统提示词；起草帖子时应用

典型的 Agent 工作流

1. get_account_group（default: true）→ 连接 ID
2. list_video_templates → 选择模板 → create_video → 轮询 get_video_status
3. upload_media（或使用渲染 URL）→ 使用 scheduledFor 调用 create_post
4. 之后：调用 get_analytics 和 get_revenue_overview 汇报结果

或者，端到端创建品牌轮播帖子：

1. generate_carousel（长篇内容 → 幻灯片文案）
2. list_carousel_styles / list_brand_kits → 选择系列和配色，或选择套件
3. render_carousel → 轮询 get_carousel_render → 获取已完成的 assets
4. 使用这些资源作为 media 调用 create_post（它们已是附件格式）

开发

npm install
npm run build      # tsc → dist/
npm test           # builds, validates server.json and the plugin manifests, boots stdio, exercises hosted OAuth mode
PLANPOST_API_KEY=pk_test_xxx node dist/index.js

该服务通过标准输入/输出传输 MCP，或使用 --http 通过可流式 HTTP 传输。它会使用你的凭据调用 PlanPost 公共 API（/api/public/v1）；不会存储或发送其他任何内容。变更记录见 CHANGELOG.md。

维护者

发布一个版本意味着需要发布两次：先将代码发布到 npm，再将元数据发布到 官方 MCP Registry。该注册表仅存储 server.json，并检查它指向的 npm 包是否存在，以及是否包含匹配的 mcpName。Glama 和其他目录会从该注册表导入信息，因此第二步决定了发布版本能否被发现。

1. 更新 package.json 中的 version，以及 server.json（顶层和 packages[0].version）、gemini-extension.json、.claude-plugin/plugin.json 和 .cursor-plugin/plugin.json 中的版本，并在 CHANGELOG.md 中添加条目。如果这些版本不一致，npm test 会失败。

2. 先发布到 npm；注册表会拒绝尚未发布到 npm 的版本：

   npm publish --access public
   

3. 安装一次发布工具 CLI（使用 brew install mcp-publisher，或从注册表的 GitHub releases 下载 tarball），然后登录。通过 GitHub 设备流以该账号登录，即可证明 io.github.lukBB/* 命名空间归你所有：

   mcp-publisher login github
   

4. 在此目录中验证并发布：

   mcp-publisher validate
   mcp-publisher publish
   

5. 确认列表：

   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.lukBB/planpost"
   

令牌过期时会显示“Invalid or expired Registry JWT token”：请重新登录。mcp-publisher status 可弃用或删除已发布的版本。 Gemini CLI 扩展库和插件市场会收录带有 GitHub 发布标签的版本，因此请在发布后为其添加 vX.Y.Z 标签。

许可证

MIT