Buffer MCP 使用与部署手册

适用版本：buffer-mcp 1.0.0 ｜平台端点：https://mcpweb.wjjnew.cn/buffer-mcp/mcp

通过 Buffer 统一发布/排期到 Facebook、Instagram、YouTube 等渠道，内置 Cloudinary 媒体上传与校验，共 23 个工具。帮助运营与办公场景实现 AI 自动化（内容排期、批量发布、媒体处理与数据分析）。平台托管开箱即用，使用你自己的 Buffer API Key。

前置条件
在平台使用（推荐）
工具清单（23）
写操作确认与权限
计费
安全与合规
本地部署
常见问题

一、前置条件

项目	是否必需	获取方式
Buffer 账号 + API Access Token	必需	Buffer 后台 → Developers / API → Access Token
Buffer 已连接至少一个渠道	必需	Buffer 后台 → Channels 连接 Facebook / Instagram / YouTube 等
Cloudinary 账号	可选	仅 `cloudinary_upload*` 需要；用媒体公网 URL 发布可不配

二、在平台使用（推荐）

注册 / 登录 → 进入 控制台。
「数据源」→ Buffer MCP 社媒发布：
- Buffer API Key（必填）；
- Cloudinary cloud name / API Key / API Secret（可选，填齐才启用）；
- 默认频道 ID（可选，逗号分隔；不填则调用时传 channelIds）；
- 发布模式：addToQueue（默认）/ shareNext / shareNow / customScheduled；
- 时区（默认 Asia/Shanghai）；
- 「允许发布/上传（写入）」默认开启；「允许修改/删除（危险）」默认关闭。
保存后实例自动重建，立即生效；已配置时 Key 可留空（仅改选项不重传）。
「API Token」→ 创建 Token（mcp_sk_...）。
客户端配置：

三、工具清单（23）

分组	工具	说明
配置（3）	`buffer_get_config` / `buffer_set_config` / `buffer_reset_config`	读取/修改/重置配置（密钥默认不可写）
渠道（3）	`buffer_list_organizations` / `buffer_list_channels` / `buffer_get_channel`	组织、已连接渠道与详情
帖子（5）	`buffer_list_posts` / `buffer_get_post` / `buffer_create_post` / `buffer_update_post` / `buffer_delete_post`	列表/详情/创建/更新/删除
媒体（7）	`cloudinary_upload` / `cloudinary_upload_batch` / `cloudinary_link` / `cloudinary_variants` / `cloudinary_delete` / `media_probe` / `media_preflight`	上传、变体、探测、发布前校验
分析（5）	`buffer_list_daily_limits` / `buffer_get_analytics` / `buffer_list_ideas` / `buffer_list_idea_groups` / `buffer_create_idea`	限额、分析、灵感

四、写操作确认与权限

工具	confirm	额外要求
`buffer_create_post`	`"create"`	允许发布/上传（写入）
`buffer_update_post`	帖子 id	允许修改/删除
`buffer_delete_post`	帖子 id	允许修改/删除
`cloudinary_upload` / `cloudinary_upload_batch`	`"upload"`	已配置 Cloudinary
`cloudinary_delete`	`public_id`	允许修改/删除

HTTP 写入还需在控制台勾选「允许发布/上传（写入）」；修改/删除还需勾选「允许修改/删除（危险）」。

五、计费（积分制）

操作	积分/次
`buffer_create_post`	3
`cloudinary_upload_batch`	3
修改/删除帖子、`buffer_get_analytics`、`cloudinary_upload`	2
列表/详情/探测/上传辅助/灵感	1
配置读取/写入/重置	0

与其它工具集共用积分；调用失败（isError）不扣费。

六、安全与合规

Buffer Key / Cloudinary Secret 经 AES-256-GCM 加密存储，明文不回显、不入日志。
Cloudinary 默认使用你本人的账号（平台不会回退到第三方账号）；不填则不启用上传。
建议为 Buffer 使用专用 Token；不需要时在控制台「删除」即可立即销毁实例。
发布内容由你自行负责，请遵守 Buffer 与各平台的服务条款与社区规范。

七、本地部署（可选）

cd buffer-mcp
npm ci --omit=dev
npm run build
BUFFER_API_KEY=你的Key node dist/index.js        # 默认 stdio
# 或 HTTP：
BUFFER_API_KEY=你的Key MCP_TRANSPORT=http MCP_HTTP_PORT=8787 node dist/index.js

客户端（stdio）：

八、常见问题

现象	原因	处理
`428` 请先配置 BUFFER 凭据	未配置数据源	控制台「数据源 → Buffer MCP」保存 Key
`401 Access token is not valid`	Key 错误/过期	重新生成 Buffer Access Token
`CLOUDINARY_NOT_CONFIGURED`	未填 Cloudinary	填 cloud name/key/secret，或改用公网媒体 URL
创建帖子报写入被拒	关闭了写入	勾选「允许发布/上传（写入）」
更新/删除被拒	未开启危险操作	勾选「允许修改/删除」，并传对 `confirm`
实例启动失败 503	依赖/端口异常	查看 `journalctl -u mcp-saas`