Postproxy

Postproxy MCP Server

用于将 Postproxy API 与 Claude Code 集成的 MCP（Model Context Protocol）服务。此服务提供用于发布帖子、检查状态，以及通过 Claude Code 管理社交媒体个人资料的工具。

安装

全局安装

npm install -g postproxy-mcp

本地安装

npm install postproxy-mcp

Claude Code 会将 MCP 服务配置保存在 ~/.claude/plugins/ 下。 安装 postproxy-mcp 后，Claude 会在重启时自动检测该服务。

配置

注册 MCP 服务

安装 postproxy-mcp 后，使用 claude mcp add 命令将其注册到 Claude Code：

claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api -- postproxy-mcp

将 your-api-key 替换为你的实际 Postproxy API 密钥。

配置会自动保存到 ~/.claude/plugins/。运行此命令后：

1. 重启 Claude Code 会话
2. 询问 Claude：“检查我的 Postproxy 身份验证状态”，以测试连接
3. 如果工具可用，Claude 就能自动使用它们

替代方案：交互式设置

非技术用户可以使用交互式设置命令：

postproxy-mcp setup

或

postproxy-mcp-setup

该命令将逐步引导你完成设置，并自动使用 claude mcp add 注册服务。

可用工具

身份验证工具

auth_status

检查身份验证状态、API 配置和工作区信息。

参数：无

返回：

{
  "authenticated": true,
  "base_url": "https://api.postproxy.dev/api",
  "profile_groups_count": 2
}

账户概览

summary_get

一次调用即可回答“状态如何？”——提供指定时间范围内的活动摘要，而不是分别调用 history_list / comments_list / dm_chats_list 并多次往返。

参数：

• window（字符串，可选）：24h（默认）、7d 或 30d
• from（字符串，可选）：ISO 8601 时间戳或用于指定范围起点的纯日期。此参数会覆盖 window，且 *_previous 计数会返回 null
• to（字符串，可选）：指定范围的终点。仅提供 from 时，默认为当前时间
• profile_group_id（字符串，可选）：仅报告单个分组。省略此参数则涵盖该密钥可访问的所有分组

返回：

{
  "window": {
    "label": "24h",
    "from": "2026-08-17T09:00:00Z",
    "to": "2026-08-18T09:00:00Z",
    "previous_from": "2026-08-16T09:00:00Z",
    "backlog_from": "2026-07-19T09:00:00Z"
  },
  "posts": {
    "published": 4,
    "published_previous": 3,
    "failed": 1,
    "scheduled_ahead": 6,
    "next_scheduled_at": "2026-08-18T14:00:00Z",
    "by_platform": { "instagram": { "published": 4, "failed": 0 } }
  },
  "engagement": {
    "total": { "impressions": 48210, "likes": 1204 },
    "by_platform": { "instagram": { "impressions": 31002, "likes": 900 } },
    "posts_with_insights": 14
  },
  "comments": { "received": 96, "received_previous": 71, "awaiting_reply": 12, "by_platform": { "instagram": 61 } },
  "reviews": { "received": 7, "received_previous": 4, "awaiting_reply": 3 },
  "dms": { "inbound": 41, "outbound": 33, "chats_awaiting_reply": 5, "reply_window_closing": 2 },
  "api": { "calls": 812, "calls_previous": 640 }
}

说明：

• 帖子数统计的是帖子数量，因此，发送到三个网络的帖子只计一次，帖子串也只计一次。by_platform 统计各网络的投递次数，因此，一个包含 3 条内容的 X 帖子串在 twitter 下计为 3。
• engagement 统计的是时间范围内发布的帖子截至当前的累计互动量，而非在该时间范围内获得的互动量——它会汇总每条帖子的最新数据快照。几分钟前发布的帖子可能还没有数据快照，因此不会计入 posts_with_insights。键名为各平台的统计字段中列出的规范化指标。
• awaiting_reply 统计的是当前状态，而非该时间范围内的情况——更改 window 不会影响这些计数。统计会回溯 30 天，结果由 window.backlog_from 返回。只有回复来自你（通过 Postproxy 或个人资料本身）时，评论才算已回复；chats_awaiting_reply 则根据消息时间戳计算，因为 Postproxy 没有已读／未读状态。
• reply_window_closing 统计剩余消息窗口不足 6 小时的聊天。没有消息窗口的网络（Telegram、Bluesky）不纳入统计。
• 账户关闭数据洞察时，engagement 为 null；关闭私信时，dms 为 null。
• 此工具与其他工具一样受范围限制：仅限某个分组的密钥只会报告该分组的数据。

个人资料管理

profile_groups_list

列出使用你的 API 密钥可访问的所有个人资料分组。个人资料分组是用于组织资料的容器（例如按品牌或客户端划分）。使用分组的 id，可通过 profile_group_id 筛选 profiles_list。

参数：无

返回：

{
  "profile_groups": [
    {
      "id": "grp123abc",
      "name": "Main Brand",
      "profiles_count": 4
    }
  ]
}

profile_groups_initialize_connection

为个人资料组中的新个人资料生成连接 URL。用户打开该 URL 即可完成 OAuth 流程。

参数：

• profile_group_id（string，必填）：个人资料组 ID
• platform（string，必填）：要连接的平台（例如 instagram、linkedin、whatsapp）
• onboarding（string，可选）：仅适用于 Instagram 和 WhatsApp。Instagram：instagram（默认值）使用 Instagram Login；facebook 使用 Facebook Login，适用于关联到你管理的 Facebook Page 的 Instagram 专业账户。无论使用哪种方式，个人资料都是 platform: "instagram"；改用另一种方式重新连接会就地更新现有个人资料。WhatsApp：api 或 business_app（参见 WhatsApp Business Management）。
• identifier + app_password（Bluesky）/ bot_token（Telegram）：凭据，仅限本地服务器

profiles_list

列出所有可用于发布帖子的社交媒体个人资料。

参数：

• profile_group_id（string，可选）：如果提供，则仅返回此组中的个人资料（使用 profile_groups_list 查找组 ID）

返回值：

{
  "profiles": [
    {
      "id": "profile-123",
      "name": "My Twitter Account",
      "platform": "twitter",
      "profile_group_id": "group-abc"
    }
  ]
}

profiles_placements

列出个人资料可用的展示位置。对于 Facebook 个人资料，展示位置为公共主页。对于 LinkedIn 个人资料，展示位置包括个人资料和组织。对于 Pinterest 个人资料，展示位置为画板。对于 Telegram 个人资料，展示位置为机器人可以发布消息的频道。对于 Google Business 个人资料，展示位置为地点，返回完整资源路径（accounts/X/locations/Y），以便传入 location_id。对于 WhatsApp 个人资料，展示位置为 Business Account 上的电话号码——展示位置 id 即 phone_number_id，所有 whatsapp_* 工具和 dm_chat_create 都需要该值。适用于 facebook、linkedin、pinterest、telegram、google_business 和 whatsapp 个人资料。

参数：

• profile_id（string，必填）：个人资料 hashid

返回值（LinkedIn 示例）：

{
  "placements": [
    {
      "id": null,
      "name": "Personal Profile"
    },
    {
      "id": "108520199",
      "name": "Acme Marketing"
    }
  ]
}

注意：

• 创建帖子时如果未指定展示位置：
  • LinkedIn：默认为个人资料
  • Facebook：默认为随机关联的公共主页（如果只关联了一个公共主页，则无需设置展示位置 ID）
  • Pinterest：会失败
  • Telegram：会失败——每条帖子都必须提供 chat_id
  • Google Business：会失败——每条帖子及每个 google_business_* 工具都必须提供 location_id

profiles_stats

获取个人资料的粉丝数/互动量时间序列。系统大约每 23 小时采集一次快照，因此你可以绘制粉丝增长和其他趋势随时间的变化图表。stats 字段采用平台原生格式（未标准化）——有关字段结构和各网络附加的个人资料级键（followers_count、followersCount 等），请参阅 post_stats 部分中的 Stats Fields by Platform。

参数：

• profile_id（string，必填）：个人资料 hashid
• placement_id（string，视情况必填）：对于 facebook、linkedin、telegram 和 google_business 个人资料为必填项。通过 profiles_placements 获取。对于 instagram、threads、youtube、twitter、tiktok、pinterest 和 bluesky，请省略此参数。
• from（string，可选）：ISO 8601 时间戳——仅包含在此时间或之后记录的快照
• to（string，可选）：ISO 8601 时间戳——仅包含在此时间或之前记录的快照

返回值（LinkedIn 示例）：

{
  "data": {
    "profile_id": "prof_li_001",
    "platform": "linkedin",
    "placement_id": "108520199",
    "records": [
      { "stats": { "followerCount": 4500, "shareCount": 8, "likeCount": 80 }, "recorded_at": "2026-05-09T08:00:00Z" },
      { "stats": { "followerCount": 4520, "shareCount": 9, "likeCount": 90 }, "recorded_at": "2026-05-10T08:00:00Z" }
    ]
  }
}

对于无需展示位置的网络（例如 Bluesky），请省略 placement_id：

{
  "data": {
    "profile_id": "prof_bsky_001",
    "platform": "bluesky",
    "placement_id": null,
    "records": [
      { "stats": { "followersCount": 8800, "postsCount": 40 }, "recorded_at": "2026-05-09T08:00:00Z" }
    ]
  }
}

帖子管理

post_publish

向指定的社交媒体个人资料发布帖子。

参数：

• content（string，必填）：帖子内容文本

• profiles（string[]，必填）：个人资料 ID（hashids）或平台名称（例如 "linkedin"、"instagram"、"twitter"）组成的数组。使用平台名称时，会向该平台上第一个已连接的个人资料发布帖子。

• schedule（string，可选）：ISO 8601 格式的预定时间

• media（string[]，可选）：媒体 URL 或本地文件路径组成的数组

• idempotency_key（string，可选）：用于去重的幂等键

• require_confirmation（boolean，可选）：如果为 true，则返回摘要而不发布

• draft（boolean，可选）：如果为 true，则创建不会自动发布的草稿帖子

• queue_id（string，可选）：要将帖子添加到的队列 ID。队列会自动分配时间段。请勿与 schedule 一起使用。

• queue_priority（string，可选）：添加到队列时的优先级：high、medium（默认）或 low

• platforms（object，可选）：平台专属参数。键为平台名称（例如 "instagram"、"youtube"、"tiktok"），值为包含平台专属选项的对象。完整文档请参阅平台参数参考。

  示例：

  {
    "instagram": {
      "format": "reel",
      "collaborators": ["username1", "username2"],
      "first_comment": "Link in bio!"
    },
    "youtube": {
      "title": "My Video Title",
      "privacy_status": "public"
    },
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true
    }
  }
  

返回：

{
  "post_id": "job-123",
  "accepted_at": "2024-01-01T12:00:00Z",
  "status": "pending",
  "draft": true
}

关于草稿帖子的说明：如果你请求创建草稿帖子（draft: true），但 API 返回 draft: false，响应中会包含一个 warning 字段，提示 API 可能忽略了草稿参数。如果 API 不支持在特定参数（例如媒体附件）下创建草稿，或在特定条件下不支持创建草稿，就可能出现这种情况。请查看响应中的 warning 字段了解详情。

post_status

通过任务 ID 获取已发布帖子的状态。

参数：

• post_id（string，必填）：来自 post.publish 响应的帖子 ID

返回：

{
  "post_id": "job-123",
  "overall_status": "complete",
  "draft": false,
  "status": "processed",
  "content": "Full post body as submitted...",
  "scheduled_at": "2024-01-02T09:00:00Z",
  "created_at": "2024-01-01T12:00:00Z",
  "source": "postproxy",
  "queue_id": null,
  "platforms": [
    {
      "platform": "twitter",
      "status": "published",
      "url": "https://twitter.com/status/123",
      "post_id": "123",
      "error": null,
      "attempted_at": "2024-01-01T12:00:00Z"
    }
  ]
}

对于立即发布的帖子，scheduled_at 为 null。平台 url 是已发布帖子的永久链接（发布前为 null）。

状态值：

• overall_status："draft"、"pending"、"processing"、"complete"、"failed"
• 平台 status："pending"、"processing"、"published"、"failed"、"deleted"
• 平台 error：发布失败时的错误消息（成功时为 null）

post_publish_draft

发布草稿帖子。只有状态为 draft: true 的帖子才能通过此端点发布。

参数：

• post_id（string，必填）：要发布的草稿帖子 ID

返回：

{
  "post_id": "job-123",
  "status": "processed",
  "draft": false,
  "scheduled_at": null,
  "created_at": "2024-01-01T12:00:00Z",
  "message": "Draft post published successfully"
}

post_delete

通过任务 ID 删除帖子。

参数：

• post_id（string，必填）：要删除的帖子 ID

返回：

{
  "post_id": "job-123",
  "deleted": true
}

post_stats

获取一个或多个帖子的统计数据快照。返回所有匹配的快照，以便查看随时间变化的趋势。支持按个人资料／网络和时间范围筛选。

参数：

• post_ids (string[], required)：帖子 hashid 数组（最多 50 个）
• profiles (string, optional)：以逗号分隔的个人资料 hashid 或网络名称列表（例如 instagram,twitter、abc123,def456 或混合使用）
• from (string, optional)：ISO 8601 时间戳——仅包含在此时间或之后记录的快照
• to (string, optional)：ISO 8601 时间戳——仅包含在此时间或之前记录的快照

返回：

{
  "data": {
    "abc123": {
      "platforms": [
        {
          "profile_id": "prof_abc",
          "platform": "instagram",
          "records": [
            {
              "stats": {
                "impressions": 1200,
                "likes": 85,
                "comments": 12,
                "saved": 8
              },
              "recorded_at": "2026-02-20T12:00:00Z"
            }
          ]
        }
      ]
    }
  }
}

各平台的统计字段：

平台	字段
Instagram	impressions、likes、comments、saved、profile_visits、follows
Facebook	impressions、clicks、likes
Threads	impressions、likes、replies、reposts、quotes、shares
Twitter	impressions、likes、retweets、comments、quotes、saved
YouTube	impressions、likes、comments、saved
LinkedIn	impressions
TikTok	impressions、likes、comments、shares
Pinterest	impressions、likes、comments、saved、outbound_clicks

注意：Instagram 快拍不会返回统计数据。TikTok 统计数据要求帖子具有公开 ID。

队列管理

queues_list

列出所有发布队列。队列会根据优先级自动将帖子安排到每周重复的时间段。

参数：

• profile_group_id (string, optional)：按个人资料组筛选队列

返回：

{
  "queues": [
    {
      "id": "q1abc",
      "name": "Morning Posts",
      "description": "Daily morning content",
      "timezone": "America/New_York",
      "enabled": true,
      "jitter": 10,
      "profile_group_id": "pg123",
      "timeslots": ["Monday at 09:00 (id: 1)", "Wednesday at 09:00 (id: 2)"],
      "posts_count": 5
    }
  ]
}

queues_get

获取单个发布队列的详细信息，包括其时间段和帖子数量。

参数：

• queue_id (string, required)：队列 ID

queues_create

创建包含每周时间段的新发布队列。

参数：

• profile_group_id (string, required)：要关联此队列的个人资料组 ID（使用 profiles_list 查找）
• name (string, required)：队列名称
• description (string, optional)：可选描述
• timezone (string, optional)：IANA 时区名称（例如 America/New_York）。默认值：UTC
• jitter (number, optional)：应用于计划时间的随机偏移分钟数（0–60），让发布模式更自然。默认值：0
• timeslots (array, optional)：初始每周时间段。每个对象包含 day（0=周日，6=周六）和 time（24 小时制 HH:MM 格式）

示例：

{
  "profile_group_id": "pg123",
  "name": "Weekday Mornings",
  "timezone": "America/New_York",
  "jitter": 10,
  "timeslots": [
    { "day": 1, "time": "09:00" },
    { "day": 2, "time": "09:00" },
    { "day": 3, "time": "09:00" },
    { "day": 4, "time": "09:00" },
    { "day": 5, "time": "09:00" }
  ]
}

queues_update

更新队列设置、时间段，或暂停／恢复队列。更改时区或时间段会触发所有队列中帖子的重新安排。

参数：

• queue_id (string, required)：要更新的队列 ID
• name (string, optional)：新的队列名称
• description (string, optional)：新的描述
• timezone (string, optional)：IANA 时区名称
• enabled (boolean, optional)：设为 false 可暂停队列，设为 true 可恢复队列
• jitter (number, optional)：随机偏移分钟数（0–60）
• timeslots (array, optional)：要添加或移除的时间段。添加：{ "day": 1, "time": "09:00" }。移除：{ "id": 42, "_destroy": true }。

queues_delete

删除发布队列。队列中的帖子将移除队列关联，但不会被删除。

参数：

• queue_id (string, required)：要删除的队列 ID

queues_next_slot

获取队列的下一个可用时间段。

参数：

• queue_id (string, required)：队列 ID

返回：

{
  "next_slot": "2026-03-11T14:00:00Z"
}

将帖子添加到队列

使用 post_publish 发布帖子时，可以将其添加到队列，而不是手动安排发布时间：

• queue_id (string, optional)：要将帖子添加到的队列 ID。队列会自动分配时间段。不要与 schedule 一起使用。
• queue_priority (string, optional)：优先级：high、medium（默认）或 low。优先级较高的帖子会获得更早的时间段。

示例：

{
  "content": "Queued post content",
  "profiles": ["twitter", "linkedin"],
  "queue_id": "q1abc",
  "queue_priority": "high"
}

评论管理

comments_list

列出已发布帖子的评论。返回带有嵌套回复的分页顶级评论。

参数：

• post_id（string，必填）：帖子 ID
• profile_id（string，必填）：用于确定要检索哪个平台评论的档案 ID
• page（number，可选）：页码，从 0 开始（默认值：0）
• per_page（number，可选）：每页的顶级评论数（默认值：20）
• from（string，可选）：ISO 8601 日期/时间——仅包含在此时间点或之后收到的评论
• to（string，可选）：ISO 8601 日期/时间——仅包含在此时间点或之前收到的评论

from/to 筛选的是 Postproxy 收到评论的时间，而不是平台的 posted_at（该字段不一定总有值）。仅输入日期（例如 2026-03-25）表示该日期的开始时间。筛选仅应用于顶级评论——即使评论在筛选范围内，也会返回其完整的 replies 数组。

返回：

{
  "total": 42,
  "page": 0,
  "per_page": 20,
  "data": [
    {
      "id": "cmt_abc123",
      "external_id": "17858893269123456",
      "body": "Great post!",
      "status": "synced",
      "author_username": "someuser",
      "like_count": 3,
      "is_hidden": false,
      "posted_at": "2026-03-25T10:00:00.000Z",
      "replies": [
        {
          "id": "cmt_def456",
          "body": "Thanks!",
          "author_username": "author",
          "parent_external_id": "17858893269123456"
        }
      ]
    }
  ]
}

评论对象还可能包含 attachments 数组（评论中的媒体——image、video、audio、gif、external、file），每项包含 id、type、url、status 和 external_id。Facebook、Threads 和 Bluesky 的评论会填充此数组；Instagram、YouTube 和 LinkedIn 的评论仅支持文本。没有媒体时，该数组为空。

comments_get

获取单条评论及其回复。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID（Postproxy ID 或平台外部 ID）
• profile_id（string，必填）：档案 ID

comments_create

在已发布的帖子上创建评论或回复。评论将异步发布到平台。

参数：

• post_id（string，必填）：帖子 ID
• profile_id（string，必填）：档案 ID
• text（string，必填）：评论文本内容
• parent_id（string，可选）：要回复的评论 ID（Postproxy ID 或外部 ID）。省略则表示直接评论帖子。

返回：

{
  "id": "cmt_ghi789",
  "body": "Thanks for the feedback everyone!",
  "status": "pending",
  "external_id": null
}

创建评论时，其 status 为 "pending"。发布到平台后，状态将变为 "published"。如果发布失败，状态将变为 "failed"。

comments_delete

异步删除平台上的评论。支持 Instagram、Facebook、YouTube 和 LinkedIn。不支持 Threads。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID（Postproxy ID 或平台外部 ID）
• profile_id（string，必填）：档案 ID

comments_edit

异步编辑你发布的评论文本。仅支持 Facebook 和 YouTube。返回 { accepted: true }；操作结果将通过 comment.edited / comment.edit_failed webhook 通知。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID（Postproxy ID 或平台外部 ID）
• profile_id（string，必填）：档案 ID
• body（string，必填）：新的评论文本

comments_hide

异步隐藏平台上的评论。支持 Instagram、Facebook 和 Threads。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID
• profile_id（string，必填）：档案 ID

comments_unhide

取消隐藏之前隐藏的评论。支持 Instagram、Facebook 和 Threads。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID
• profile_id（string，必填）：档案 ID

comments_like

异步为平台上的评论点赞。目前仅支持 Facebook。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID
• profile_id（string，必填）：档案 ID

comments_unlike

取消对评论的点赞。目前仅支持 Facebook。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID
• profile_id（string，必填）：档案 ID

平台支持

操作	Instagram	Facebook	Threads	YouTube	LinkedIn
列出	支持	支持	支持	支持	支持
回复	支持	支持	支持	支持	支持
删除	支持	支持	不支持	支持	支持
隐藏/取消隐藏	支持	支持	支持	不支持	不支持
点赞/取消点赞	不支持	支持	不支持	不支持	不支持

私信

在支持私信的个人资料上进行 1:1 消息交流（聊天和消息）。支持 Facebook（Messenger）、Instagram（私信）、Telegram（机器人私信）、Bluesky 和 WhatsApp。发送的消息会异步处理（返回 status: "pending"）。Meta 的 24 小时消息窗口适用于 Facebook/Instagram——如果人工回复的是参与者主动发起的咨询，可传入 tag: "HUMAN_AGENT"，在窗口外发送消息（最多 7 天，绝不能用于促销或自动化内容）；Telegram 和 Bluesky 没有时间窗口限制。在 WhatsApp 上，只有发送已获批准的模板（template）或 category: "utility" 文本才能重新开启消息窗口——WhatsApp 的其他功能请参阅 WhatsApp Business 管理。

dm_chats_list

列出个人资料的聊天，并按最近活动时间排序。

参数：

• profile_id（string，必填）：个人资料 ID（Facebook、Instagram、Telegram、Bluesky 或 WhatsApp）
• page（number，可选）：页码，从 0 开始（默认：0）
• per_page（number，可选）：每页项目数（默认：20）
• before / after（string，可选）：按 last_message_at 筛选的 ISO 8601 时间戳

WhatsApp 聊天还包含 external_placement_id（聊天所属的电话号码）、group（群聊时为 true）和 within_messaging_window。

dm_chat_create

查找或为参与者创建聊天（幂等——如果聊天已存在，则返回现有聊天）。在向个人资料尚未联系过的参与者发送消息前使用。

参数：

• profile_id（string，必填）：个人资料 ID
• participant_external_id（string，必填）：平台参与者 ID（IG 范围内的用户 ID、Facebook PSID、Telegram 用户 ID、Bluesky DID，或带国家/地区代码的 WhatsApp 电话号码——非数字字符会被移除）
• placement_id（string，可选）：profiles_placements 中的 Placement ID。WhatsApp 上必填（聊天所属的电话号码）；Facebook 上可选（主页 ID）
• participant_username（string，可选）
• participant_name（string，可选）

全新的 WhatsApp 对话尚未开启消息窗口，因此首次发送必须使用 template（参见 dm_message_send）。

dm_chat_get

通过 Postproxy ID 或平台 external_conversation_id 获取单个聊天。

参数：

• chat_id（string，必填）：聊天 ID 或外部对话 ID

dm_messages_list

列出聊天中的消息，按最新消息优先排序。

参数：

• chat_id（string，必填）：聊天 ID 或外部对话 ID
• page（number，可选）：页码，从 0 开始（默认：0）
• per_page（number，可选）：每页项目数（默认：20）
• direction（string，可选）：inbound 或 outbound
• status（string，可选）：按消息状态筛选

dm_message_send

发送一条外发消息。必须且只能提供 body（文本）、media（单个附件）之一；或者在 WhatsApp 上提供 template、interactive、location 或 contacts。

参数：

• chat_id（字符串，必填）：聊天 ID 或外部对话 ID
• body（字符串，可选）：消息文本（未发送其他内容时必填；在 WhatsApp 上也可与 media 一起作为说明文字）
• media（字符串数组，可选）：最多一个附件，可使用 URL 或本地文件路径。Bluesky 不支持。（远程/Worker MCP 仅接受 URL。）WhatsApp 限制：图片 5MB，格式为 jpeg/png；视频 16MB，格式为 mp4/3gpp；音频 16MB；文档 100MB。
• tag（字符串，可选）：HUMAN_AGENT 用于在 24 小时窗口外发送消息——从参与者最后一条入站消息起将窗口延长至 7 天（仅限 Facebook/Instagram）。Meta 限定此标记仅供人工回复参与者本人发起的咨询；将其用于营销、优惠或自动重新互动，可能导致该主页 / Instagram 账号的消息功能被暂停。超过 7 天后，Meta 会拒绝发送，消息的状态将变为 status: failed，平台错误会显示在 error_details 中。
• reply_to_external_id（字符串，可选）：Telegram 和 WhatsApp——要引用 / 在线程中回复的平台消息 ID（Telegram 的 message_id、WhatsApp 的 wamid）
• reply_markup（对象，可选）：仅限 Telegram——内联键盘 / 回复键盘负载
• quick_replies（对象数组，可选）：仅限 Facebook 和 Instagram——最多 13 个可点击的快捷回复，显示在参与者的输入框上方。每项为 { title, payload }。
• buttons（对象数组，可选）：仅限 Facebook 和 Instagram——附加到消息上的按钮，最多 3 个。每项为 { type: "web_url", title, url } 或 { type: "postback", title, payload }。
• card（对象，可选）：仅限 Facebook 和 Instagram——承载 buttons 的卡片的额外字段（subtitle、image_url、default_action）。需要提供 buttons。
• template（对象，可选）：仅限 WhatsApp——发送已获批准的模板：{ id | name, language, variables[], button_params[], header_media, header_location }。这是在 24 小时窗口外发送消息或开启新对话的唯一方式。
• interactive（对象，可选）：仅限 WhatsApp——Meta 格式的交互式消息（回复按钮、列表、cta_url、商品、flow、位置请求），将原样传递
• location（对象，可选）：仅限 WhatsApp——{ latitude, longitude, name, address }
• contacts（对象数组，可选）：仅限 WhatsApp——采用 Meta 的 contacts 格式的联系人卡片
• category（字符串，可选）：仅限 WhatsApp——"utility" 会将纯文本消息标记为实用型 Direct Send，可在没有模板的情况下于窗口外发送
• link_preview（布尔值，可选）：仅限 WhatsApp——false 会关闭文本消息中的 URL 预览
• voice_note（布尔值，可选）：仅限 WhatsApp——将 OGG/Opus 音频附件作为语音消息发送
• filename（字符串，可选）：仅限 WhatsApp——文档附件的显示名称

快速回复和按钮

仅限 Facebook Messenger 和 Instagram Direct——在 Telegram 上请改用 reply_markup（传入这些参数会返回 422）。快速回复是临时选项，点击后即消失；按钮则会继续显示在对话线程中的消息上。

	quick_replies	buttons
每次发送上限	13	3
title	必填，≤20 个字符	必填，≤20 个字符
payload	必填，≤1000 个字符	postback 必填，≤1000 个字符
url	—	web_url 必填，必须为 https://
是否需要 body	否	是，且 body 最多 80 个字符
与 media 一起使用	仅限 Facebook	不允许

{
  "chat_id": "chat_xyz789",
  "body": "What can I help with?",
  "quick_replies": [
    { "title": "Track order", "payload": "TRACK" },
    { "title": "Talk to support", "payload": "HELP" }
  ]
}

{
  "chat_id": "chat_xyz789",
  "body": "Nike Air Max",
  "card": { "subtitle": "$129 · Arriving Friday", "image_url": "https://cdn.example.com/shoe.png" },
  "buttons": [
    { "type": "web_url", "title": "Buy now", "url": "https://shop.example.com/p/air-max" },
    { "type": "postback", "title": "Notify me", "payload": "NOTIFY:air-max" }
  ]
}

按钮会作为 Meta 通用模板发送，其元素标题就是你的 body——这就是 80 个字符上限的由来。Instagram 的限制比 Messenger 更严格：它只会在纯文本消息中发送快速回复，因此在 Instagram 上将 quick_replies 与 media 或 buttons 一起使用会返回 422。

接收点击事件：点击的选项或按钮回传会作为一条入站消息传入，并携带 tapped_action：{ "kind": "quick_reply" | "postback" | "callback_query", "payload": "...", "title": "..." }。请从 dm_messages_list / dm_message_get 中读取，而不是去 platform_data 中查找。Instagram 的破冰问题点击事件和 Telegram 回调查询也会统一为同一字段。

WhatsApp 模板和交互式消息

WhatsApp 号码只能在参与者的 24 小时窗口开启时（聊天上的 within_messaging_window）发送自由格式文本、媒体、interactive、location 和 contacts。超出窗口后——包括由你主动发起的对话——请发送已审核通过的模板。variables 按顺序填充占位符（先是标题文本变量，再是正文变量，最后是动态 URL 按钮变量），并且必须与 whatsapp_templates_list 中模板的 variable_count 一致；渲染后的正文会存储在消息中。

{
  "chat_id": "chat_wa1",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": ["Ana", "ORD-12345"]
  }
}

带媒体标题的模板使用 header_media: { "link": "https://..." }；位置标题使用 header_location；URL / 复制代码 / 流程按钮使用 button_params: [{ "index": 0, "sub_type": "url", "parameters": [{ "type": "text", "text": "12345" }] }]。

在窗口期内，interactive 是 Meta 自有的对象——可用于回复按钮（最多 3 个）、列表（最多 10 行）、CTA URL、商品卡片、流程或位置请求：

{
  "chat_id": "chat_wa1",
  "interactive": {
    "type": "button",
    "body": { "text": "Ready to confirm your booking?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
        { "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } }
      ]
    }
  }
}

点击后会作为一条入站消息返回，其 body 为所点击的标题，回复 id 位于 platform_data.interactive 下。在 WhatsApp 上使用 Facebook/Instagram 的 quick_replies / buttons 会返回 422；在其他所有网络上使用 template / interactive / location / contacts / category 会返回 422。

dm_message_get

通过 Postproxy ID 或平台 external_id 获取单条消息。

参数：

• message_id（字符串，必填）：消息 ID 或 external ID

dm_message_edit

编辑之前发送的出站消息。**仅限 Telegram。**请提供 body 和/或 reply_markup（传入 {} 可清除键盘）；至少需要提供其中一项。

参数：

• message_id（字符串，必填）：消息 ID 或 external ID
• body（字符串，可选）：新文本/说明
• reply_markup（对象，可选）：新键盘（或 {} 以移除）

dm_message_react / dm_message_unreact

添加或移除你的商家账号在消息上的表情回应。Facebook Messenger、Instagram Direct 和 WhatsApp。

参数（dm_message_react）：

• message_id（字符串，必填）：消息 ID 或 external ID
• reaction（字符串，可选）：命名表情回应（默认值为 love）。在 WhatsApp 上会被忽略
• emoji（字符串，可选）：Unicode 表情符号。在 WhatsApp 上必填（任意表情符号）

参数（dm_message_unreact）：

• message_id（字符串，必填）

dm_chat_archive / dm_chat_unarchive

归档（静音）或取消归档（取消静音）聊天。**仅限 Bluesky。**返回 archived 已设置的聊天。

参数：

• chat_id（字符串，必填）：聊天 ID 或外部对话 ID

dm_chat_mark_read

将聊天标记为已读。在 WhatsApp 上，这会为最新收到的消息发送已读回执（蓝色双勾）；在其他网络上，只会写入 metadata.read_at。返回该聊天。

参数：

• chat_id（string，必填）：聊天 ID 或外部会话 ID

dm_comment_private_reply

向评论作者发送私信，作为对该评论的回复（Meta“私密回复”）。可绕过 24 小时窗口（评论最多可发布 7 天），并自动创建或复用聊天。每条评论只能发送一次私密回复。仅限 Instagram 和 Facebook。

参数：

• post_id（string，必填）：帖子 ID
• comment_id（string，必填）：评论 ID 或外部 ID
• profile_id（string，必填）：资料 ID（Instagram 或 Facebook）
• text（string，必填）：私信文本
• quick_replies（array，可选）：最多 13 个选项，与 dm_message_send 的格式相同
• buttons（array，可选）：最多 3 个按钮，与 dm_message_send 的格式相同；text 最多 80 个字符
• card（object，可选）：buttons 的卡片样式（subtitle、image_url、default_action）

交互元素遵循与 dm_message_send 相同的规则——在 Instagram 上，quick_replies 和 buttons 不能同时使用。私密回复不支持媒体附件。

平台支持

操作	Facebook	Instagram	Telegram	Bluesky	WhatsApp
列出/发送/获取	是	是	是	是	是
媒体附件	是	是	是	否	是（允许添加说明文字）
编辑消息	否	否	是	否	否
表情回应/取消回应	是	是	否	否	是（emoji）
归档/取消归档	否	否	否	是	否
标记为已读（已发送回执）	仅本地	仅本地	仅本地	仅本地	是
评论私密回复	是	是	否	否	否
tag（24 小时窗口）	是	是	不适用	不适用	否 — 使用 template / category: utility
reply_to_external_id	否	否	是	否	是
reply_markup	否	否	是	否	否
quick_replies / buttons / card	是	是（仅文本）	否	否	否 — 使用 interactive
template / interactive / location / contacts	否	否	否	否	是
收到点击时的 tapped_action	是	是	是	否	否（参见 platform_data.interactive）

历史记录

history_list

列出最近的帖子任务。

参数：

• limit（number，可选）：要返回的任务数上限（默认值：10）

返回：

{
  "jobs": [
    {
      "post_id": "job-123",
      "content": "Full post body as submitted...",
      "content_preview": "Post content preview...",
      "created_at": "2024-01-01T12:00:00Z",
      "overall_status": "complete",
      "status": "processed",
      "scheduled_at": "2024-01-02T09:00:00Z",
      "draft": false,
      "source": "postproxy",
      "queue_id": null,
      "platforms_count": 2,
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "url": "https://x.com/user/status/123"
        }
      ]
    }
  ]
}

对于立即发布的帖子，scheduled_at 为 null。status 是原始 API 状态（draft、scheduled、processing、processed 等），而 overall_status 则将各平台的结果汇总为单一判定。

注意：Postproxy 的 /posts API 不会返回各平台的资料身份信息（资料 ID 或名称），只会返回网络。使用 profiles_list 将网络映射到已连接的资料。

Google Business Profile 管理

这些工具用于编辑 Google 商家资料本身的内容——营业时间、属性、服务、餐饮菜单、操作链接和资料照片——而不是向其中发布本地动态（发布动态使用 post_publish，平台为 google_business）。

此组中的所有工具都适用以下三条规则：

1. 始终需要 location_id。 这是完整的 Google 资源路径 accounts/X/locations/Y，由 profiles_placements 返回。
2. 更新使用字段掩码。 每次写入都需要一个 fields 数组，用于准确指定要替换的内容。在 fields 中指定但载荷中缺少的字段会被清空；嵌套对象会被整体替换，而不是合并。修补前务必先读取。
3. 可用性因类别和地区而异。 不同商家资料可用的属性、服务列表、餐饮菜单和操作链接类型各不相同。请先列出可用项；不符合条件的位置会返回 422。

载荷使用 Google 自有的数据结构和 camelCased 键，因此响应可以直接作为请求正文发送。

工具	用途
google_business_location_get	读取商家资料——名称、描述、网站、电话、类别、地址、营业时间、服务区域、元数据
google_business_location_update	更新商家资料字段（title、websiteUri、phoneNumbers、categories、storefrontAddress、serviceArea、labels、latlng、openInfo、profile、storeCode）
google_business_categories_list	查询某个地区的类别资源名称（categories/gcid:*）——更新任何 categories 字段时都需要
google_business_hours_update	设置 regularHours、specialHours 和 moreHours
google_business_attributes_get	读取当前已设置的属性
google_business_attributes_available	列出此商家资料可设置的属性及其值类型
google_business_attributes_update	设置属性
google_business_service_list_get	读取服务列表
google_business_service_list_update	替换服务列表（需要 metadata.canModifyServiceList）
google_business_food_menus_get	读取餐饮菜单（仅适用于餐厅类类别）
google_business_food_menus_update	替换餐饮菜单（需要 metadata.canHaveFoodMenus）
google_business_place_action_links_list	列出操作按钮（“在线预约”“在线订购”）
google_business_place_action_types_available	列出 Google 接受的位置操作类型
google_business_place_action_link_create	添加操作按钮
google_business_place_action_link_update	更新操作按钮
google_business_place_action_link_delete	移除操作按钮
google_business_media_list	列出资料照片和视频
google_business_media_create	添加照片或视频
google_business_media_delete	移除照片或视频

典型流程

1. profiles_placements                    → get location_id
2. google_business_location_get           → read current state
3. google_business_attributes_available   → see what this listing accepts
4. google_business_attributes_update      → patch only what changed

属性值形态

google_business_attributes_available 会为每个属性返回一个 valueType，它决定了要发送的数据形态：

valueType	形态
BOOL	{ "name": "attributes/offers_online_appointments", "values": [true] }
URL	{ "name": "attributes/url_linkedin", "uriValues": [{ "uri": "https://..." }] }
ENUM	{ "name": "attributes/preferred_messaging_service", "repeatedEnumValue": { "setValues": ["TOKEN"] } }

attribute_mask 默认恰好包含你发送的名称，因此部分更新不会清除未包含在内的属性。

营业时间

时间可以使用 "09:00" / "09:00:00" 字符串，也可以使用 Google 的 { "hours": 9, "minutes": 0 } 对象——调用前两种格式都会被规范化。通过 google_business_location_get 读取当前营业时间；fields 中指定的每个时间段都会被整体替换。

{
  "fields": ["regularHours"],
  "regularHours": {
    "periods": [
      { "openDay": "MONDAY", "openTime": "09:00", "closeDay": "MONDAY", "closeTime": "18:00" }
    ]
  }
}

媒体

Google 会直接从 media_url 下载文件——无需上传，因此该 URL 必须是可公开访问的 https URL（不能是短时效签名 URL，也不能是 localhost）。图片尺寸至少为 250×250，且文件大小不得超过 5MB。category 默认为 ADDITIONAL；只有打算更改个人资料页眉或徽标时，才使用 COVER 或 LOGO。

阅读空结果

Google 会省略键，而不是返回空值：不含属性的商家信息会返回 { "name": "..." }，完全没有 attributes 键；serviceItems、placeActionLinks 以及 isPreferred 等布尔标志也是如此。请将缺失值视为空值。

分析

Google Business 地点分析数据通过标准的 profiles_stats 工具提供——将 location_id 作为 placement_id 传入。指标包括 Search 和 Maps 展示次数（桌面端和移动端）、网站点击次数、电话点击次数、路线请求次数、对话数、预订数、食品订单数和食品菜单点击次数。Google Business 没有关注者数量，Google 也不提供本地帖子级别的分析数据。

WhatsApp Business 管理

管理已连接的 WhatsApp Business 账户，不仅限于收件箱：消息模板、电话号码状态和注册、公开的商务资料、显示名称和用户名、已屏蔽用户、群组，以及 Click-to-WhatsApp 转化报告。对话本身通过上文的 dm_* 工具处理。

本组中的每个工具都适用以下四条规则：

1. WhatsApp Business 账户（WABA）是资料；其上的每个电话号码都是一个投放位置。 按电话号码范围操作的工具需要 phone_number_id——即 profiles_placements 中的投放位置 id（其元数据包含 display_phone_number、quality_rating、messaging_limit_tier、name_status、platform_type）。
2. 模板和 Conversions 数据集属于 WABA 级别——这些工具只需要 profile_id。
3. 仅可在 24 小时窗口内发送自由格式消息。 参与者最近一条入站消息超过 24 小时（或对话是新建的）后，dm_message_send 只接受已 APPROVED 的 template（或 category: "utility" 文本）。模板送达后会重新开启此窗口。
4. 共存号码受到限制。 使用 onboarding: "business_app" 连接的号码（仍在手机上的 WhatsApp Business 应用中）吞吐量较低，且无法使用 Groups API；对于这些号码，whatsapp_number_info 返回的 platform_type 不为 CLOUD_API。

当返回 Meta 的数据结构时，响应会使用 Meta 自身的字段名称（components、interactive、商务资料字段）。

工具	用途
whatsapp_templates_list	列出已同步的模板（筛选 name、language、status；refresh: true 会先从 Meta 重新同步）
whatsapp_template_get	获取一个模板及其组件、状态和 variable_count
whatsapp_template_create	提交自定义模板（components）或实例化一个库模板（library_template_name）
whatsapp_template_update	修改 components（状态会变回 PENDING 审核）和／或 message_send_ttl_seconds
whatsapp_template_delete	删除某种语言的模板（language）或删除整个名称
whatsapp_template_library_get	实例化 Meta 库模板前查看其详情
whatsapp_number_info	实时号码和 WABA 状态：质量评级、消息层级、名称状态、平台类型
whatsapp_number_register	使用 6 位 PIN 通过 Cloud API 注册号码
whatsapp_number_request_verification_code	为未验证的号码请求短信／语音验证码
whatsapp_number_verify	提交验证码
whatsapp_business_profile_get	公开资料：简介、地址、描述、电子邮件、网站、行业类别、照片
whatsapp_business_profile_update	更新这些字段（about ≤139，description ≤512，网站最多 2 个）
whatsapp_business_profile_photo_update	替换资料照片（url 或 base64 data；JPEG/PNG ≤5MB）
whatsapp_display_name_get	查看已验证的显示名称和审核状态
whatsapp_display_name_request_change	提交新的显示名称供 Meta 审核
whatsapp_username_get / _set / _delete / _suggestions	管理该号码的 wa.me 用户名
whatsapp_blocked_users_list / whatsapp_blocked_user_status	查看已屏蔽的用户
whatsapp_users_block / whatsapp_users_unblock	每次调用最多屏蔽／取消屏蔽 1000 个号码
whatsapp_groups_list / _create / _get / _update / _delete	该号码管理的群组（仅限 Cloud API 号码）
whatsapp_group_participants_add / _remove	管理成员（一个群组最多容纳 8 人）
whatsapp_group_invite_link_create	创建新的邀请链接（会撤销之前的链接）
whatsapp_group_join_requests_list / _approve / _reject	处理需审批群组的加入请求
whatsapp_dataset_get / whatsapp_dataset_create	WABA 上的 Conversions API 数据集
whatsapp_conversion_event_send	为 Click-to-WhatsApp 对话报告 LeadSubmitted / Purchase / AddToCart / InitiateCheckout / ViewContent 事件

典型流程

1. profile_groups_initialize_connection   → platform: whatsapp (onboarding: api | business_app)
2. profiles_placements                    → get phone_number_id
3. whatsapp_templates_list                → find an APPROVED template and its variable_count
4. dm_chat_create                         → participant_external_id: phone, placement_id: phone_number_id
5. dm_message_send                        → template: { name, language, variables }
6. dm_messages_list                       → the reply opens a 24h window; free-form sends now work

连接号码

profile_groups_initialize_connection 配合 platform: "whatsapp" 会返回一个连接 URL。如果号码位于手机上的 WhatsApp Business 应用中，请传入 onboarding: "business_app"（用户扫描二维码；该应用可与 Postproxy 同时使用，并会导入最多 6 个月的聊天记录）；如果号码属于其他提供商或是全新号码，请传入 onboarding: "api"（号码将迁移到 Cloud API，之后无法再在应用中使用）。省略该参数时，连接页面会询问用户。每个 WhatsApp Business Account 会成为一个 profile，其每个号码都会成为一个 placement。

模板

Meta 会审核每个自定义模板；新模板在获批前状态为 PENDING，只有状态为 APPROVED 的模板才能发送。占位符可以是 {{1}}、{{2}}……（parameter_format: POSITIONAL，默认值），也可以是 {{name}}（NAMED）。模板的 variable_count 表示发送时必须提供的 variables 数量：先是标题文本占位符，再是正文占位符，最后是每个动态 URL 按钮各一个。库模板（whatsapp_template_library_get → whatsapp_template_create 配合 library_template_name）无需审核。每种语言的模板名称必须唯一；按名称删除而不指定 language 时，会删除所有语言版本。

转化

从点击 WhatsApp 广告开始的对话会在聊天的 metadata 中带有 ctwa_clid。创建一次数据集（whatsapp_dataset_create），然后使用 whatsapp_conversion_event_send，通过 chat_id 或 phone 上报结果；如果聊天未捕获到 ctwa_clid，则会返回 422。

示例提示词

以下是一些可与 Claude Code 搭配使用的示例提示词：

检查身份验证

Check my PostProxy authentication status

列出 Profiles

Show me all my available social media profiles

发布帖子

使用 profile ID：

Publish this post: "Check out our new product!" to profiles ["profile-123"]

使用平台名称：

Publish "Exciting news!" to linkedin and twitter

Instagram Reel 音频

工具	描述
instagram_available_audio	搜索 Meta 的音乐／原创声音库（未提供 search_query 时显示热门内容）；将 audio_id 传给 Reel

仅适用于通过 Facebook Login 连接的 Instagram profiles（profile_groups_initialize_connection 配合 onboarding: "facebook"）；Instagram Login profiles 会返回 422。

使用平台参数发布

你可以使用特定于平台的参数，为各个平台自定义帖子。platforms 参数接受一个对象，其键为平台名称，值包含特定于平台的选项。

Instagram 示例

带协作者的普通帖子：

Publish to Instagram: "Amazing content!" to my Instagram account with collaborators username1 and username2

或使用显式参数：

{
  "content": "Amazing content!",
  "profiles": ["instagram"],
  "media": ["https://example.com/image.jpg"],
  "platforms": {
    "instagram": {
      "format": "post",
      "collaborators": ["username1", "username2"],
      "first_comment": "What do you think? 🔥"
    }
  }
}

Instagram Reel：

{
  "content": "Check out this reel! #viral",
  "profiles": ["instagram"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "instagram": {
      "format": "reel",
      "collaborators": ["collaborator_username"],
      "cover_url": "https://example.com/thumbnail.jpg",
      "audio_name": "Trending Audio",
      "first_comment": "Link in bio!"
    }
  }
}

使用库音乐的 Instagram Reel（适用于 Facebook Login profiles；从 instagram_available_audio 获取 audio_id）：

{
  "content": "Summer vibes ☀️",
  "profiles": ["instagram"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "instagram": {
      "format": "reel",
      "audio_id": "1234567890123456",
      "audio_volume": 80,
      "strip_audio": true
    }
  }
}

audio_volume／video_volume 的取值范围为 1–100（默认值为 100）。strip_audio 会移除视频自身的声音（Reel 和视频快拍），适用于任何 Instagram profile。

Instagram 快拍：

{
  "profiles": ["instagram"],
  "media": ["https://example.com/story-image.jpg"],
  "platforms": {
    "instagram": {
      "format": "story"
    }
  }
}

YouTube 示例

带标题和隐私设置的 YouTube 视频：

Upload this video to YouTube with title "My Tutorial" and make it public

或使用显式参数：

{
  "content": "This is the video description with links and details",
  "profiles": ["youtube"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "youtube": {
      "title": "My Tutorial: How to Build an API",
      "privacy_status": "public",
      "cover_url": "https://example.com/custom-thumbnail.jpg"
    }
  }
}

不公开的 YouTube 视频：

{
  "content": "Video description",
  "profiles": ["youtube"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "youtube": {
      "title": "Private Tutorial",
      "privacy_status": "unlisted"
    }
  }
}

TikTok 示例

公开发布并自动添加音乐的 TikTok：

{
  "content": "Check this out! #fyp",
  "profiles": ["tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true,
      "disable_comment": false,
      "disable_duet": false,
      "disable_stitch": false
    }
  }
}

仅对关注者可见并带有 AI 标签的 TikTok：

{
  "content": "Special content for followers",
  "profiles": ["tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "tiktok": {
      "privacy_status": "FOLLOWER_OF_CREATOR",
      "made_with_ai": true,
      "brand_content_toggle": false
    }
  }
}

Facebook 示例

带首条评论的 Facebook 帖子：

{
  "content": "Check out our new product!",
  "profiles": ["facebook"],
  "media": ["https://example.com/product.jpg"],
  "platforms": {
    "facebook": {
      "format": "post",
      "first_comment": "Link to purchase: https://example.com/shop"
    }
  }
}

Facebook 快拍：

{
  "profiles": ["facebook"],
  "media": ["https://example.com/story-video.mp4"],
  "platforms": {
    "facebook": {
      "format": "story"
    }
  }
}

Facebook 公共主页帖子：

{
  "content": "Company announcement",
  "profiles": ["facebook"],
  "platforms": {
    "facebook": {
      "page_id": "123456789",
      "first_comment": "Visit our website for more details"
    }
  }
}

LinkedIn 示例

个人 LinkedIn 帖子：

{
  "content": "Excited to share my latest article on AI",
  "profiles": ["linkedin"],
  "media": ["https://example.com/article-cover.jpg"]
}

公司 LinkedIn 帖子：

{
  "content": "We're hiring! Join our team",
  "profiles": ["linkedin"],
  "media": ["https://example.com/careers.jpg"],
  "platforms": {
    "linkedin": {
      "organization_id": "company-id-12345"
    }
  }
}

Bluesky 示例

纯文本 Bluesky 帖子（自动识别提及／标签／链接）：

{
  "content": "Hey @jay.bsky.team — check out our latest #ruby post: https://example.com/blog/post",
  "profiles": ["bluesky"]
}

无需添加任何标记——Postproxy 会自动将 @handles、#tags 和 URL 转换为 AT Protocol facets，并根据 URL 的 Open Graph 元数据生成链接卡片预览（未附加媒体时）。上限为 300 个字素。

Telegram 示例

Telegram 频道帖子（HTML 格式）：

{
  "content": "<b>New release</b> — read more on our blog https://example.com/post",
  "profiles": ["telegram"],
  "platforms": {
    "telegram": {
      "chat_id": "-1001234567890",
      "parse_mode": "HTML",
      "disable_link_preview": true,
      "disable_notification": false
    }
  }
}

对你的 Telegram profile 使用 profiles_placements，即可列出机器人可以发布内容的频道 chat_id。必须将机器人添加为频道管理员，并授予其发布权限。

跨平台示例

相同内容，不同平台：

{
  "content": "New product launch! 🚀",
  "profiles": ["instagram", "twitter", "linkedin"],
  "media": ["https://example.com/product.jpg"]
}

在不同平台发布带有特定参数的视频：

{
  "content": "Product launch video",
  "profiles": ["instagram", "youtube", "tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "instagram": {
      "format": "reel",
      "first_comment": "Link in bio!"
    },
    "youtube": {
      "title": "Product Launch 2024",
      "privacy_status": "public",
      "cover_url": "https://example.com/yt-thumbnail.jpg"
    },
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true
    }
  }
}

平台参数参考

Instagram：

• format：「post」|「reel」|「story」
• collaborators：用户名数组（帖子最多 10 个，Reel 最多 3 个）
• first_comment：字符串——发布后添加的评论
• cover_url：字符串——Reel 的缩略图 URL
• audio_name：字符串——Reel 的音轨名称
• trial_strategy：「MANUAL」|「SS_PERFORMANCE」——Reel 的试用策略
• thumb_offset：字符串——Reel 的缩略图偏移量，单位为毫秒
• user_tags：{ username, x, y, media_index } 数组——在任意格式（帖子、Reel、Story）中标记公开的 Instagram 账号。图片必须提供 x 和 y（从左上角起算的浮点数，范围为 0.0–1.0）；Reel 和视频轮播页仅按用户名标记（坐标会被丢弃）；Story 可以接受坐标，但不需要坐标。media_index 用于选择轮播页（从 0 开始，默认值为 0）。开头的 @ 会被移除。超出范围的坐标、超过最后一个媒体项的 media_index，或图片标签缺少 x/y 时，都会被拒绝并返回一个指出相应条目的 422 错误。Instagram 会静默跳过私人账号和关闭了标记功能的账号。

YouTube：

• title：字符串——视频标题
• privacy_status：「public」|「unlisted」|「private」
• cover_url：字符串——自定义缩略图 URL

TikTok：

• privacy_status：「PUBLIC_TO_EVERYONE」|「MUTUAL_FOLLOW_FRIENDS」|「FOLLOWER_OF_CREATOR」|「SELF_ONLY」
• photo_cover_index：整数——用作封面的照片索引（从 0 开始）
• auto_add_music：布尔值——启用自动添加音乐
• made_with_ai：布尔值——将内容标记为 AI 生成
• disable_comment：布尔值——关闭评论
• disable_duet：布尔值——关闭合拍
• disable_stitch：布尔值——关闭拼接
• brand_content_toggle：布尔值——标记为付费合作（三方）
• brand_organic_toggle：布尔值——标记为付费合作（自有品牌）

Facebook：

• format：「post」|「story」
• first_comment：字符串——发布后添加的评论
• page_id：字符串——用于向公司主页发布内容的主页 ID

LinkedIn：

• organization_id：字符串——公司主页帖子的组织 ID

Telegram：

• chat_id：字符串，必填——目标频道/聊天 ID（使用 profiles_placements 列表查看）
• parse_mode：「HTML」|「MarkdownV2」——纯文本时省略
• disable_link_preview：布尔值——关闭 URL 预览卡片
• disable_notification：布尔值——静默发送（不播放通知声音）
• 字符限制：纯文本为 4,096；附带媒体时，说明文字限制为 1,024（超出部分会被截断）
• 媒体：图片 ≤10 MB（×10），视频 ≤50 MB（×10），文档 ≤50 MB（×1）
• 机器人必须是目标频道的成员（最好具有发布权限的管理员）

Bluesky：

• 没有特定于平台的参数
• 字符限制：300 个字素簇（表情符号和组合序列各计为一个）
• 自动检测 @handle.bsky.social 提及、#hashtags 和 URL，并将其转换为可点击的标记
• 存在 URL 且未附加媒体时，会根据 Open Graph 元数据生成链接卡片预览
• 媒体：图片 ≤1 MB（×4），视频 ≤100 MB（×1，1–60 秒）
• 支持通过标准 thread 数组发布串帖

Twitter/X 和 Threads：

• 没有特定于平台的参数

完整文档请参阅平台参数参考。

创建草稿帖子

Create a draft post: "Review this before publishing" to linkedin

发布草稿帖子

Publish draft post job-123

检查帖子状态

What's the status of job job-123?

这将显示详细状态，包括草稿状态、平台特定错误和发布结果。

删除帖子

Delete post job-123

获取帖子统计数据

Show me the stats for post abc123

Get stats for posts abc123 and def456 filtered to Instagram only, from February 1st to today

列出发布位置

Show me the placements for my LinkedIn profile prof123

队列管理

Show me all my posting queues

Create a queue called "Weekday Mornings" for profile group pg123, timezone America/New_York, with timeslots Monday through Friday at 9am

Add a post to queue q1abc with high priority: "Check out our latest feature!"

Pause queue q1abc

What's the next available slot for queue q1abc?

评论管理

Show me the comments on post abc123 for my Instagram profile prof456

Reply to comment cmt_abc123 on post abc123 with "Thanks for the feedback!" using profile prof456

Hide comment cmt_abc123 on post abc123 for profile prof456

私信

List the DM chats for my Instagram profile prof456

Reply "Yes, we ship worldwide!" in chat chat_xyz789

Send a DM to the author of comment cmt_abc123 on post abc123 from profile prof456 saying "DM-ing you the details"

Open a WhatsApp chat with +1 310 555 0007 on number 1055512345 of profile prof_wa and send the order_update template in en_US with Ana and ORD-12345

Mark chat chat_wa1 as read and react to the last inbound message with 🔥

WhatsApp Business 管理

List the approved WhatsApp templates on profile prof_wa

Create a UTILITY template called appointment_reminder in en_US on profile prof_wa: "Hi {{1}}, your appointment is on {{2}} at {{3}}."

Show the quality rating and messaging tier for number 1055512345 on profile prof_wa

Update the WhatsApp business profile of number 1055512345 on prof_wa: about "Open Mon–Sat 9–18", website https://acme.example

Block +1 310 555 0099 on number 1055512345 of profile prof_wa

Report a Purchase of 49.90 USD for chat chat_wa1 on profile prof_wa with event id ord-9921

查看历史记录

Show me the last 5 posts I published

故障排除

服务无法启动

• 检查 API 密钥：使用 claude mcp add 注册时，请确保已设置 POSTPROXY_API_KEY
• 检查 Node 版本：需要 Node.js >= 18.0.0
• 检查安装情况：确认已安装 postproxy-mcp，且该程序位于 PATH 中
• 检查注册情况：确保已通过 claude mcp add 注册服务，并且配置已保存到 ~/.claude/plugins/

身份验证错误

• AUTH_MISSING：未配置 API 密钥。运行 claude mcp add 时，请确保包含 --env POSTPROXY_API_KEY=...
• AUTH_INVALID：API 密钥无效。请确认 API 密钥正确。

验证错误

• TARGET_NOT_FOUND：一个或多个配置文件 ID 不存在。使用 profiles_list 查看可用配置文件。
• VALIDATION_ERROR：帖子内容或参数无效。API 现在会返回详细的错误消息：
  • 400 errors：{"status":400,"error":"Bad Request","message":"..."}
  • 422 errors：{"errors": ["Error 1", "Error 2"]} - 验证错误消息数组
  • 请查看错误消息，了解具体的验证问题

API 错误

• API_ERROR：Postproxy API 返回了错误。请查看错误消息了解详情。
• 超时：请求耗时超过 30 秒。请检查网络连接和 API 状态。

平台错误

使用 post_status 检查帖子状态时，现在可以在每个平台对象的 error 字段中查看平台专属错误：

• error: null - 帖子已成功发布
• error: "Error message" - 平台 API 返回的详细错误消息
• 常见错误包括身份验证问题、速率限制、内容违规等。

草稿帖子问题

如果创建了草稿帖子（draft: true），但响应中返回 draft: false：

• 响应中会包含 warning 字段，说明 API 可能忽略了草稿参数
• 可能出现此情况的原因：
  • API 不支持带媒体附件的草稿
  • API 对特定条件下的草稿帖子有限制
• 请查看响应中的 warning 字段了解详情
• 启用调试模式（POSTPROXY_MCP_DEBUG=1）以查看有关草稿参数处理的详细日志

调试模式

注册服务时，将 POSTPROXY_MCP_DEBUG=1 设置为启用调试日志：

claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api --env POSTPROXY_MCP_DEBUG=1 -- postproxy-mcp

开发

从源代码构建

git clone https://github.com/postproxy/postproxy-mcp
cd postproxy-mcp
npm install
npm run build

在开发模式下运行

npm run dev

许可证

MIT