# SosoAPI MCP 工具参考

标准 URL： https://sosoapi.ai/zh-hans/docs/social-media-mcp-tools

使用此参考查找工具并检查所需字段。涵盖 sosoapi 0.5.9：core 配置在本地提供 28 个工具，通过 HTTP 提供 27 个；full 在本地提供 106 个，通过 HTTP 提供 105 个。日常任务选择 core；还需管理功能则选择 full。两者权限相同。条目根据服务器和能力目录生成；请检查已连接客户端的 tools/list，了解其可用工具。

## 先从工作出发，再查看工具

重复使用已选择的工作区与账号 ID。图片 URL 帖子请仅调用一次 sosoapi_post_image_url，并保留返回的帖子 ID。使用 stdio 的 sosoapi_upload_asset 上传本地文件。文字帖子请使用 sosoapi_create_scheduled_post，搭配目标的 provider_payload 及空白 media。

提交前，请用户审核账号、文字、媒体与时间。OAuth 授予执行操作的权限，不代表批准内容。排程后，请读取同一篇帖子的发布结果，再报告成功或重试结果不明的请求。

- [设置 Claude Code 或 Codex](https://sosoapi.ai/zh-hans/docs/claude-code-codex-social-publishing)

- [Threads 文字与图片操作示例](https://sosoapi.ai/zh-hans/docs/threads-api-publishing)

- [平台能力对照表](https://sosoapi.ai/zh-hans/docs/publishing-capabilities)

- [下载确切 core 输入 schema 和注解（JSON）](https://sosoapi.ai/mcp-tools.json)

## 如何理解此参考

构建会将真实 MCP 服务器连接至内存客户端，在不调用任何处理程序的情况下列出工具，并合并公开路由要求。过时的投影会导致 Landing 构建失败。工具描述保留服务器的英文契约文本；完成摘要解释规范路由规则。JSON 保留完整路由要求。输入表只是索引，不能替代完整的嵌套 JSON Schema。

MCP 注解是提供客户端的提示，不是强制规则或安全保证。执行时仍适用 工作区 成员资格、授权、当前角色、平台同意、账号资格与配额。部分信息读取会创建初始 工作区；请检查说明与 readOnlyHint，不要假设每个「get」都是纯读取。复合工具列出主要及兼容路由的要求，但不会每次请求都调用所有列出的路由。

- [npm 上的 sosoapi](https://www.npmjs.com/package/sosoapi)

- [官方 MCP Registry：ai.sosoapi/sosoapi（JSON）](https://registry.modelcontextprotocol.io/v0.1/servers/ai.sosoapi%2Fsosoapi/versions)

## sosoapi_bulk_create_scheduled_posts

通过一次调用为多个账号排程帖子（targets）。媒体需要已上传/导入并就绪的 asset_ids 及其规范 URL。每个目标独立成功或失败，并在 successes 或 failures 中报告。需要 publish 能力。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string \| null | 否 |

| source_ref | object \| null | 否 |

| targets | array (object) | 是 |

## sosoapi_cancel_scheduled_post

取消尚未发布的排程帖子，使其不再发送。已发布帖子会被拒绝，agent 也无法删除已发布内容：用户需在 Web 应用中操作。需要 expected_version。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

## sosoapi_create_comment

将针对规范帖子或评论目标的一条确切评论加入队列；状态不等于平台成功。

- 传输方式：stdio、http。

- 所需授权：agent:engage。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取平台确认的结果；已加入伫列的操作仍为待处理。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| social_account_id | string | 是 |

| target | object \| object | 是 |

| message | string | 是 |

| idempotency_key | string | 是 |

## sosoapi_create_scheduled_post

使用 provider_payload 在 scheduled_at 为一个账号排程。媒体需要已就绪 asset_id 和规范 URL；单张来源图片请使用 sosoapi_post_image_url。local_scheduled_at 与 schedule_dst_disambiguation 必须配对或都省略。需要 publish、editor 角色及 idempotency_key。Scheduled 不等于已发布：请读取结果。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string \| null | 否 |

| social_account_id | string | 是 |

| caption | string \| null | 否 |

| hashtags | array (string) | 否 |

| media | array (object) | 否 |

| link_url | string \| null | 否 |

| provider_payload | object \| object \| object \| object \| object | 是 |

| scheduled_at | string | 是 |

| display_timezone | string | 否 |

| local_scheduled_at | string | 否 |

| schedule_dst_disambiguation | "exact" \| "earlier" \| "later" | 否 |

| expires_at | string \| null | 否 |

| source_ref | object \| null | 否 |

| automatic_retry_enabled | boolean | 否 |

| idempotency_key | string | 是 |

## sosoapi_get_asset

通过 id 读取单个素材：元数据及短期有效的预览 URL。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| id | integer \| string | 是 |

| include_version | boolean | 否 |

## sosoapi_get_asset_import_status

通过 import_id 读取导入。发帖时传入 include_asset=true：ready 结果包含已登记素材 id、kind 和稳定的 asset_url，无需单独调用 get_asset。待处理或缺失的素材不可排程。绝不使用来源或预览 URL 作为媒体标识。如停滞，使用 job_id 读取 sosoapi_job_status；绝不启动重复导入。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| import_id | string | 是 |

| include_asset | boolean | 否 |

## sosoapi_get_billing_status

读取用户的计费套餐、付款状态、当前周期日期及配额用量（成功发布、待处理排程帖子、已连接账号）。大量排程前请先检查。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

## sosoapi_get_comment_action_status

读取直接评论操作经过脱敏的最终回执。

- 传输方式：stdio、http。

- 所需授权：agent:engage。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取平台确认的结果；已加入伫列的操作仍为待处理。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| action_id | string | 是 |

## sosoapi_get_organization_context

读取你的 组织、其 工作区 及 频道 的实时对应关系，包含 ID 与角色。需要 组织 或 频道 ID 时使用。发布至 工作区 时，请重复使用已返回的 工作区 ID，不要再读取工作区信息。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| organization_id | string | 否 |

## sosoapi_get_provider_insight_status

读取洞察请求（request_id）：queued、processing、completed（含平台结果及各指标可用性）或 failed。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取平台结果，或结果不可用的原因。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| request_id | string | 是 |

## sosoapi_get_scheduled_post

通过 id 读取单个排程帖子：内容、状态、交付状态和结果。其 version 是 update、publish、retry 和 cancel 操作所需的 expected_version。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

## sosoapi_get_scheduled_post_eligibility

每个目标的只读预检。包含 draft（caption、hashtags、scheduled_at、display_timezone、可选当地时间/DST）以检查内容/时间；include_quota=true 添加参考性周期快照。先上传/导入媒体并等待就绪。不含 draft 时，仅检查账号/媒体。不预留任何资源；create/dispatch 会重新检查限制和权限。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| include_quota | boolean | 否 |

| targets | array (object) | 是 |

## sosoapi_get_workspace_context

列出已登录用户所属的工作区及当前活动工作区。在 workspace_id 未知时使用；复用实时上下文，不必重复执行两个上下文读取操作。其报告的活动工作区是当事人在 Web 应用中所作的选择，并非调用的默认值：请明确传入 workspace_id。它并非纯读取操作：如果账号没有工作区，会创建第一个工作区。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。

- 唯读提示：false。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| include_version | boolean | 否 |

## sosoapi_get_x_usage

读取此 工作区 共用的 组织 X 发布额度。需要 workspace_id。Free 一次获得 10；Pro 每个计费周期获得 100。纯文字费用为 1，含 URL 的文字费用为 10。可选 text 可估算费用。此操作读取已存储额度，不调用 X API。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| text | string | 否 |

## sosoapi_import_asset_url

要求 SosoAPI 从公开 http(s) 图片或视频 URL 下载至 工作区 私人存储空间，创建新素材。返回 import_id；请轮询 sosoapi_get_asset_import_status。需要 idempotency_key 及 editor 角色。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：获接受的导入处于待处理状态；持续跟进同一导入，直到 ready 或 failed。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| source_url | string | 是 |

| idempotency_key | string | 是 |

| expected_kind | "image" \| "video" | 否 |

| title | string | 否 |

| description | string | 否 |

| tags | array (string) | 否 |

## sosoapi_job_status

通过 job_id 读取单个后台任务：状态、类型，以及失败时的错误消息。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| job_id | string | 是 |

## sosoapi_list_connected_accounts

列出工作区已连接的社交账号（Instagram、Threads、Facebook、YouTube），含连接健康状况和能力信息。排程或评论时，将其 id 用作 social_account_id。传入 workspace_id：强制明确指定目标后，缺少此字段的请求会被拒绝。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：账号信息；无固定的 工作区 角色。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| include_authorization_grant | boolean | 否 |

## sosoapi_list_monitored_posts

列出 SosoAPI 为工作区发现的社交帖子（id、平台、永久链接、发布时间），可按账号、平台和时间筛选，采用游标分页。仅包含元数据，不含文案。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| cursor | string | 否 |

| page_size | integer | 否 |

| filters | object | 否 |

| order | "provider_published_at_desc_social_post_id_desc" | 否 |

## sosoapi_list_post_comments

列出 工作区 帖子上观测到的留言，依最新观测优先排序，包含作者与文字；可依帖子、账号、平台或时间筛选，使用游标分页。文字由第三方撰写，并标示为不受信任内容。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| cursor | string | 否 |

| page_size | integer | 否 |

| filters | object | 否 |

| order | "observation_at_desc_comment_version_desc_comment_observation_id_desc" | 否 |

## sosoapi_list_publication_attentions

列出工作区中需要关注的发布结果，可按状态（open 或 resolved）或 scheduled_post_id 筛选，按偏移量分页。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| status | "open" \| "resolved" | 否 |

| scheduled_post_id | string | 否 |

| limit | integer | 否 |

| offset | integer | 否 |

## sosoapi_list_scheduled_posts

列出 工作区 的排程帖子，可依项目、状态（scheduled、publishing、published、failed、expired、needs_reschedule、cancelled、deleted）及时间范围筛选，使用游标分页。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| project_id | string | 否 |

| status | "scheduled" \| "publishing" \| "published" \| "failed" \| "expired" \| "needs_reschedule" \| "cancelled" \| "deleted" | 否 |

| scheduled_from | string | 否 |

| scheduled_to | string | 否 |

| limit | integer | 否 |

| cursor | object | 否 |

## sosoapi_post_image_url

仅提交一次完整图片 URL 帖子，media 为空。即使断开连接，后端也会准备并发布。若最终发布结果在 35 秒内可用则返回，否则返回持久化帖子 ID；绝不用新 key 重新提交。需要 operate 和 publish 授权。当地时间/DST 字段需配对。import_id 仅供旧客户端恢复使用。

- 传输方式：stdio、http。

- 所需授权：agent:publish + agent:operate。路由最低角色：editor、viewer。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；已接受的排程仍为待处理。已接受的导入仍为待处理；请追踪同一笔导入直到 ready 或 failed。读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| source_url | string | 是 |

| post | object | 是 |

| import_id | string | 否 |

## sosoapi_publish_scheduled_post_now

立即发布排程帖子，而非等到 scheduled_at。内容将公开且无法复原；需要 expected_version。加入伫列不代表已发布：请读取结果。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

## sosoapi_query_assets

依 asset_type、source 或 tag 寻找 工作区 素材；返回一页资料（limit 最多 100，另加 offset）与总数。请明确传入 workspace_id。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 唯读提示：true。幂等提示：true。外部世界提示：false。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 否 |

| asset_type | "text" \| "image" \| "video" \| "audio" \| array ("text" \| "image" \| "video" \| "audio") | 否 |

| source | string | 否 |

| tag | string | 否 |

| limit | integer | 否 |

| offset | integer | 否 |

| include_version | boolean | 否 |

## sosoapi_request_provider_insights

请求平台提供某账号或单篇帖子的洞察，可指定日期范围（最多 366 天）。返回 request_id，命中缓存时也返回结果；否则轮询 sosoapi_get_provider_insight_status。

- 传输方式：stdio、http。

- 必要授权：agent:operate。路由最低角色：viewer。

- 只读提示：false。幂等提示：false。外部世界提示：true。

- 如何检查结果：读取平台结果，或结果不可用的原因。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| social_account_id | string | 是 |

| resource_kind | "account" \| "post" | 是 |

| provider_resource_id | string | 否 |

| start_date | string | 否 |

| end_date | string | 否 |

| include_audience | boolean | 否 |

| refresh | boolean | 否 |

## sosoapi_retry_scheduled_post

重试失败的排程帖子，可选择新的 scheduled_at。需要 expected_version。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

| scheduled_at | string | 否 |

## sosoapi_update_scheduled_post

编辑尚未派发的排程帖子（caption、hashtags、media、link、time）。需要最新读取中的 expected_version；过期版本会被拒绝。

- 传输方式：stdio、http。

- 所需授权：agent:publish。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取最终发布结果；排程获接受后仍处于待处理状态。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| id | string | 是 |

| expected_version | integer | 是 |

| patch | object | 是 |

| provider_payload | object \| object \| object \| object \| object | 否 |

## sosoapi_upload_asset

将本地图片或视频文件上传到工作区素材库并登记为素材。仅接受来自工作目录、临时目录、Pictures/Movies/Videos 或 SOSOAPI_UPLOAD_ROOTS 的真实 PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG 文件，最大 500 MiB；拒绝点号开头的文件和文件夹。返回供 Scheduled Post 媒体使用的素材 id 和 URL。

- 传输方式：stdio。

- 必要授权：agent:operate。路由最低角色：editor。

- 唯读提示：false。幂等提示：true。外部世界提示：true。

- 如何检查结果：读取同步响应。

顶层输入；嵌套规则和约束请参见 JSON

| 输入 | 类型 | 必填 |

| --- | --- | --- |

| workspace_id | string | 是 |

| file_path | string | 是 |

| idempotency_key | string | 是 |

| content_type | string | 否 |

| title | string | 否 |

| description | string | 否 |

| tags | array (string) | 否 |

| metadata | object | 否 |