> ## 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>