> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

> 将 n8n 的 AI Agent 连接到 Ayrshare MCP Server，用一次调用即可在 13 个社交网络上发布、排期和分析，无需为每个平台编写单独的 API 代码。

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  <strong>One-time setup per Ayrshare account.</strong> You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do <em>not</em> create a new app per customer.
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

n8n 是把各类工具串联起来的地方。而 Ayrshare 是一个统一的 API，可以在一次调用中同时发布到 Facebook、Instagram、LinkedIn、YouTube、TikTok、Pinterest、Reddit、Threads、Bluesky、Telegram、Google Business Profile、Snapchat 和 X。通过 [Ayrshare MCP Server](/additional/mcp-action-server) 将两者连接后，你的 n8n AI Agent 就可以独立完成整个闭环：草拟帖子、按每个平台的规则校验、发布或排期，然后回读分析数据。

<img class="center" src="https://mintcdn.com/ayrshare-docs/bAaTGuhaX8NvaXu8/images/packages-guides/n8n-mcp-workflow.webp?fit=max&auto=format&n=bAaTGuhaX8NvaXu8&q=85&s=a04e6040568f404db97046feb0066c53" alt="The n8n starter workflow on the canvas: a chat trigger into an AI Agent, with an Anthropic chat model and the Ayrshare MCP tool node attached below, plus setup and usage sticky notes." width="2000" height="1100" data-path="images/packages-guides/n8n-mcp-workflow.webp" />

由于 MCP Server 是一个托管的 Streamable HTTP 端点，你只需通过 n8n 内置的 **MCP Client Tool** 节点即可连接。无需自行托管，无需自定义代码，也无需安装社区节点。让一个节点指向一个 URL，你的代理就能获得全部 27 个社交工具。

<Card title="下载 n8n 起步工作流" icon="download" href="/files/ayrshare-n8n-mcp-workflow.json" horizontal>
  上图所示的工作流，可直接导入：Chat Trigger、AI Agent、Anthropic 聊天模型，以及预先接入并配置了"先校验"系统提示词的 Ayrshare MCP 节点。
</Card>

使用方法：在 n8n 中打开 **Workflows → Import from file**，选择该 JSON 文件，然后创建它所需的两个凭据（一个存放 Ayrshare 密钥的 **Bearer Auth** 凭据，以及一个 **Anthropic API** 凭据）。附上凭据后，两个警告标记会自动消失。自托管实例需要能够访问 `api.ayrshare.com` 和你使用的模型服务商。

本指南将端到端讲解以 MCP 为核心的路径。如果你更愿意搭建一个固定的、非代理式工作流，最后有一段简短的 [REST 回退方案](#rest-fallback-no-agent)。

## 为什么使用 MCP 而不是手写 API 调用

你完全可以直接从 HTTP Request 节点调用 Ayrshare 的 REST API，对于固定、可预测的工作流这没问题。但当有 LLM 参与回路时，MCP Server 就显现出价值：

<ul class="custom-bullets">
  <li>**由代理选择工具。** 只需描述目标（"把这条内容发布到我们的业务频道，并把跟进内容排期到周二"），代理会自行选择 `validate_post`、`create_post` 以及正确的参数。</li>
  <li>**任何内容上线前都会校验。** `validate_post` 会按每个平台的长度、格式和媒体规则对内容进行干跑校验，避免代理发出一条会被平台拒绝的帖子。</li>
  <li>**一次调用，多个平台。** 一次 `create_post` 就能扇出到所有已关联的平台。</li>
  <li>**平台变更由 Ayrshare 负责应对。** 当某个平台修改其 API 时，由 Ayrshare 维护集成，你的工作流照常运行。</li>
  <li>**与 REST API 遵循相同的规则。** 每一次 MCP 工具调用都会在进程内通过同一条 Ayrshare API 处理链运行：相同的认证、限流、配额和校验。你无需学习一套独立的行为规则。</li>
</ul>

## 连接方式

**AI Agent** 节点是大脑。**MCP Client Tool** 子节点挂载在其上，连接到位于 `https://api.ayrshare.com/mcp` 的 Ayrshare MCP Server，发现可用工具并暴露给代理。当代理执行动作时，节点会将调用分发给 Ayrshare，由后者发布到各个平台。

```
Trigger  ->  AI Agent (+ Chat Model)  ->  MCP Client Tool  ->  Ayrshare MCP Server  ->  13 networks
```

有关端点、传输方式和身份认证的详细信息，请参见 [Connect & Setup](/additional/mcp-action-connect)。完整工具列表请参见 [工具目录](/additional/mcp-action-tools)。

## 前置条件

<ul class="custom-bullets">
  <li>一个 **n8n 实例**（Cloud 或自托管），版本较新，具备 AI Agent 和 MCP Client Tool 节点。MCP Client Tool 节点是内置的。由于 Ayrshare 服务器使用 Streamable HTTP，你无需安装社区节点。</li>
  <li>一个 **Ayrshare 账户和 API 密钥**（Dashboard → Settings → API Key），或开启一个[免费试用](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h)。</li>
  <li>在 Ayrshare 中 **至少已连接一个社交账户**。代理只能发布到你已连接的账户。</li>
  <li>用于 AI Agent 节点的 **聊天模型凭据**（Anthropic、OpenAI 等）。</li>
  <li>*(可选)* 如果你计划通过子配置文件管理多个客户，需要 **Business 或 Enterprise 套餐**。</li>
</ul>

## 配置 MCP Client Tool 节点

<Steps>
  <Step title="添加 AI Agent 节点">
    打开或新建一个工作流，添加 **AI Agent** 节点（位于 *Advanced AI* 节点下）。
  </Step>

  <Step title="挂载 MCP Client Tool 节点">
    在 AI Agent 节点上，点击 **Tool** 连接器并添加 **MCP Client Tool** 节点。配置如下：

    | 字段                   | 值                              |
    | -------------------- | ------------------------------ |
    | **Endpoint**         | `https://api.ayrshare.com/mcp` |
    | **Server Transport** | `HTTP Streamable`              |
    | **Authentication**   | `Bearer Auth`                  |
    | **Tools to Include** | `All`（或选择 `Selected` 仅暴露指定工具）  |
  </Step>

  <Step title="将你的 Ayrshare 密钥添加为 Bearer 凭据">
    在 **Credential** 处，创建一个新的 **Bearer Auth** 凭据，并将 Ayrshare API 密钥粘贴为令牌。n8n 会以 `Authorization: Bearer YOUR_API_KEY` 的形式发送。保存后，n8n 会完成连接并列出全部 27 个工具。
  </Step>

  <Step title="接入聊天模型和系统提示词">
    挂载 **Chat Model** 子节点，选择你的模型凭据。为代理设置一个明确规则的系统提示词，例如：

    > 你是一名社交媒体助手，可以使用 Ayrshare 工具。在发布任何内容之前，请始终先调用 `validate_post` 并报告任何问题。仅在校验通过后才调用 `create_post`。默认发布到用户点名的平台；若未指明，则询问用户。绝不臆造媒体 URL；仅使用用户提供的 URL，若有疑问请通过 `validate_media` 进行确认。
  </Step>

  <Step title="添加触发器">
    测试时，**Manual Trigger** 或 **Chat Trigger** 最方便。在生产环境中，使用任何能启动该工作流的方式（定时、Webhook、表单、表格新增行等）。
  </Step>
</Steps>

<Note>
  **请使用 HTTP Streamable，不要使用 SSE。** Ayrshare MCP Server 使用现代化的 Streamable HTTP 传输方式，且为无状态。n8n 的 SSE 选项已弃用，服务器会拒绝 SSE 数据流。请始终选择 **HTTP Streamable**。
</Note>

## 工具面

你的代理通过这一个 MCP 节点即可看到全部 27 个工具。你几乎不需要按名字直接调用它们；只需描述意图，代理会自行选择。领域包括 Posts、History、Analytics、Comments、Messages、Profiles、Media、Generate、Webhooks 和 Errors。完整列表以及每个工具的用途和作用范围，请参见 [工具目录](/additional/mcp-action-tools)。

其中有两个工具在安全性上尤为突出：**`validate_post`** 使用与 `create_post` 相同的输入进行干跑，但不会发布任何内容；**`explain_error`** 会把任何 Ayrshare 错误码翻译成清晰的原因和修复建议，方便代理自我诊断。

## 示例 1：从一条聊天消息出发，草拟、校验并发布

这是本集成的"Hello World"。用聊天消息或表单触发工作流，剩下的交给代理。

<ul class="custom-bullets">
  <li>**触发器：** Chat Trigger（或带有"我们应该发布什么？"字段的 Form Trigger）。</li>
  <li>**给代理的提示：** *"为我们全新的分析仪表盘写一段友好的发布公告，并发布到 LinkedIn、Facebook 和 Instagram。请先校验。"*</li>
</ul>

代理会自行完成：使用你的文案和这三个平台调用 `validate_post`；如果 Instagram 提示缺少图片，它会告诉你，而不是静默失败；校验通过后调用 `create_post` 并返回已上线的帖子 URL。由于校验先行，你能在任何内容公开之前先发现问题。

## 示例 2：将新内容自动跨平台发布

无需人工操作，将某个内容源转化为多平台帖子。

<ul class="custom-bullets">
  <li>**触发器：** 针对你博客 feed 的 RSS Read 节点、来自 CMS 的 Webhook，或 Google Sheets / Airtable 中新增的一行。</li>
  <li>**AI Agent 步骤：** *"将这篇文章总结为一条简短的社交帖子，附带 2 到 3 个相关话题标签，然后校验并发布到 LinkedIn、Facebook 和 Threads。"*</li>
  <li>可以选择在 `create_post` 步骤之前添加一个 [人工回环](#keep-a-human-in-the-loop) 审批，让人签字后再发布。</li>
</ul>

你可以借助 `recommend_hashtags` 获取数据驱动的话题标签；如果希望由 Ayrshare 而不是你的聊天模型来草拟文案，也可以使用 `generate_post`。

## 示例 3：每周分析摘要

反向运行整个闭环：读取表现并汇报。

<ul class="custom-bullets">
  <li>**触发器：** Schedule 节点，例如每周一早 8 点。</li>
  <li>**AI Agent 步骤：** *"拉取上周 LinkedIn、Instagram 和 Facebook 的账户级分析数据，按互动量总结前 3 条帖子。"*</li>
  <li>代理会使用 `get_social_network_analytics` 获取账户级数据、`get_post_analytics` 获取单条帖子数据，然后你把它的总结通过 **Slack**、**Gmail** 或 **Notion** 节点输出。</li>
</ul>

关于频率：大多数帖子的绝大部分互动都发生在前 24 小时，指标也不会每秒更新。每天或每周一次的调度已经足够。请不要每几分钟就轮询一次分析数据，否则你会在没有新数据的情况下触发限流。

## 代表客户操作（多租户）

如果你为多个客户管理社交媒体，Ayrshare 的配置文件（profiles）可以让一个账户发布到多套相互独立的已关联账户。在 Business 或 Enterprise 套餐下，你可以从 n8n 通过两种方式定位客户：

<ul class="custom-bullets">
  <li>**按连接：** 在 MCP Client Tool 节点上添加 `Profile-Key` 请求头（使用 **Multiple Headers** 认证方式，以便同时发送 `Authorization` 和 `Profile-Key`）。该节点上的每一次调用都将以该客户的身份执行。适用于一个工作流服务于一个客户的场景。</li>
  <li>**按调用：** 许多工具接受 `profileKey` 参数，代理可以按操作设置。当两者同时存在时，[本次调用的参数优先生效](/additional/mcp-action-connect#precedence-argument-wins-over-header)。适用于一个工作流在多个客户之间路由的场景。</li>
</ul>

要接入新客户，代理可以先调用 `create_profile`，然后调用 `generate_jwt_social_linking_url` 生成一个托管页面，客户在该页面上关联自己的账户。凭据不会流经你的工作流。

## 发布到 X/Twitter

<XByoNotice />

在 n8n 中，将 MCP Client Tool 节点的 **Authentication** 切换为 **Multiple Headers**，并在 `Authorization` 旁添加两个 `X-Twitter-OAuth1-*` 请求头。这是每个 Ayrshare 账户的一次性设置，同一对密钥适用于所有配置文件。对于其他平台（Facebook、Instagram、LinkedIn、YouTube、TikTok 等）无需额外请求头。请参见 [Connect & Setup → X/Twitter BYO 凭据](/additional/mcp-action-connect#xtwitter-byo-credentials)。

## 保持人工回环

MCP 工具让代理发布内容非常轻松 —— 这也正是你应该对其加以约束的原因。两种低成本的保护措施：

<ul class="custom-bullets">
  <li>**始终先校验。** 在系统提示词中固化"先 `validate_post` 再 `create_post`"。校验不会发布任何内容，并能提前捕获平台规则违规。</li>
  <li>**添加审批步骤。** 在草稿与发布动作之间插入 n8n 的 **Send and Wait for Response**（Slack 或邮件）节点，让人在任何内容上线前先审批。对于已排期的内容，代理可以使用 `update_post` 修改等待审批的帖子。</li>
</ul>

## REST 回退方案（无代理）

如果你想要一个固定、确定、不含 LLM 的工作流，可以跳过 MCP，改用 **HTTP Request** 节点调用 REST API：

<ul class="custom-bullets">
  <li>**Method：** `POST`</li>
  <li>**URL：** `https://api.ayrshare.com/api/post`</li>
  <li>**Authentication：** Header Auth，`Authorization: Bearer YOUR_API_KEY`</li>
</ul>

```json theme={"system"}
{
  "post": "Excited to announce our new feature!",
  "platforms": ["facebook", "linkedin", "instagram"],
  "mediaUrls": ["https://example.com/image.jpg"],
  "scheduleDate": "2026-07-01T10:00:00Z"
}
```

请使用 API 主机 `api.ayrshare.com`，而不是控制台主机 `app.ayrshare.com`。（`app.ayrshare.com` 也会接受 API 调用，但它不是官方文档中的端点，可能会返回间歇性的 [502/504 网关错误](/help-center/technical-support/response_bad_gateway_502_or_504_error)，因此请始终使用 `api.ayrshare.com`。）同样的方式适用于其他 [REST 端点](/apis/overview)。当工作流完全可预测、也不需要代理来做决定时，这就是最合适的方案。

## 故障排查

| 症状                                          | 可能原因            | 修复方法                                                                                    |
| ------------------------------------------- | --------------- | --------------------------------------------------------------------------------------- |
| 工具调用返回 `403` / 代码 `102`，"API Key not valid" | API 密钥错误或缺失     | 检查 Bearer Auth 凭据保存的正是你的 Ayrshare 密钥。修改后请重新保存节点。                                        |
| n8n 无法连接到 MCP 服务器                           | 传输方式或端点错误       | 端点必须为 `https://api.ayrshare.com/mcp`；传输方式必须为 **HTTP Streamable**，而不是 SSE。               |
| X/Twitter 发帖失败并返回错误 `419`                   | 缺失 X BYO 凭据     | 通过 Multiple Headers 认证方式添加两个 `X-Twitter-OAuth1-*` 请求头。                                  |
| 仅有某个平台发帖失败                                  | 该平台未关联，或缺失必填字段  | 在控制台中关联该平台；YouTube 需要 `title`，Reddit 需要 `title` + `subreddit`，Instagram 需要 `mediaUrls`。 |
| Instagram 帖子被拒                              | 缺少媒体            | Instagram 对大部分帖子类型都要求 `mediaUrls`。让代理通过 `validate_media` 确认。                            |
| 以文件或二进制形式附加的媒体未出现                           | MCP 仅支持 JSON    | 请通过公开的 `mediaUrls` URL 引用媒体；MCP 路径不接受文件上传。请通过 `validate_media` 确认该 URL。                 |
| 调用可以成功，但作用在了错误的客户上                          | 配置文件定位问题        | 设置 `Profile-Key` 请求头（按连接）或 `profileKey` 参数（按调用）；两者同时设置时，参数优先。                           |
| `429 Too Many Requests`                     | 轮询过于频繁          | 降低分析与评论的轮询频率；指标不会每秒更新。                                                                  |
| 配置修改未生效                                     | MCP 连接在会话启动时初始化 | 修改密钥或请求头后，请重新保存节点或重启工作流。                                                                |

你也可以把 `explain_error` 工具暴露给代理，让它自己把 Ayrshare 错误码解读为原因和修复建议。

## 后续步骤

<CardGroup cols={2}>
  <Card title="Connect & Setup" icon="plug" href="/additional/mcp-action-connect" horizontal>
    端点、传输方式、身份认证、配置文件定位与 BYO 凭据。
  </Card>

  <Card title="工具目录" icon="list" href="/additional/mcp-action-tools" horizontal>
    按领域分组的 27 个工具，包含作用范围与用途。
  </Card>

  <Card title="MCP Server" icon="server" href="/additional/mcp-action-server" horizontal>
    MCP Server 是什么，以及它如何映射到 Ayrshare API。
  </Card>

  <Card title="Claude Code 插件" icon="terminal" href="/additional/mcp-claude-code-plugin" horizontal>
    同一台服务器，专为 Claude Code 打包。
  </Card>
</CardGroup>