n8n - Ayrshare API Documentation

n8n 是把各種工具串接起來的地方。而 Ayrshare 是一組統一的 API，可以在一次呼叫中同時發布到 Facebook、Instagram、LinkedIn、YouTube、TikTok、Pinterest、Reddit、Threads、Bluesky、Telegram、Google Business Profile、Snapchat 與 X。透過 Ayrshare MCP Server 將兩者連接後，你的 n8n AI Agent 就能獨立完成整個流程：草擬貼文、依每個平台的規則進行驗證、發布或排程，然後回讀分析資料。

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.

由於 MCP Server 是一個受管的 Streamable HTTP 端點，你只需要透過 n8n 內建的 MCP Client Tool 節點即可連接。不需要自行代管、不需要自訂程式碼，也不需要安裝社群節點。將一個節點指向一個 URL，你的代理程式就能取得全部 27 個社群工具。

下載 n8n 起始工作流程

上圖顯示的工作流程，可直接匯入：Chat Trigger、AI Agent、Anthropic 聊天模型，以及已預先接好並設定「先驗證」系統提示的 Ayrshare MCP 節點。

使用方式：在 n8n 中選擇 Workflows → Import from file，選取該 JSON 檔案，然後建立它預期的兩組憑證（一組存放 Ayrshare 金鑰的 Bearer Auth 憑證，以及一組 Anthropic API 憑證）。附上憑證後，兩個警告標記會消失。自架的執行個體需要能對外存取 api.ayrshare.com 與你使用的模型服務商。本指南將完整說明以 MCP 為主的路徑。如果你更想建立一個固定、非代理式的工作流程，最後有一段簡短的 REST 備援方案。

為什麼使用 MCP 而不是自己寫 API 呼叫

你當然可以直接從 HTTP Request 節點呼叫 Ayrshare 的 REST API，對於固定、可預期的工作流程，這樣就足夠了。但一旦流程中有 LLM 參與，MCP Server 的價值就出現了：

由代理程式挑選工具。 描述目標（「把這則內容發布到我們的商業頻道，並把後續內容排程到週二」），代理程式會自行選擇 validate_post、create_post 以及正確的參數。
任何內容上線前都會驗證。 validate_post 會依每個平台的長度、格式與媒體規則對內容進行試跑，避免代理程式送出一則會被平台退件的貼文。
一次呼叫，多個平台。 一次 create_post 就能扇出到所有已連結的平台。
平台變更由 Ayrshare 負責處理。 當某個平台變更其 API 時，Ayrshare 會維護整合，你的工作流程照常運作。
與 REST API 遵循相同規則。 每一次 MCP 工具呼叫都會在行程內透過同一條 Ayrshare API 處理鏈執行：相同的驗證、流量限制、配額與資料驗證。你不需要學習另一套獨立的行為規則。

連接方式

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。完整工具清單請參見工具目錄。

前置需求

一個 n8n 執行個體（Cloud 或自架），版本較新，具備 AI Agent 與 MCP Client Tool 節點。MCP Client Tool 節點是內建的。由於 Ayrshare 伺服器使用 Streamable HTTP，你不需要安裝社群節點。
一個 Ayrshare 帳戶與 API 金鑰（Dashboard → Settings → API Key），或啟用免費試用。
在 Ayrshare 中 至少已連結一個社群帳戶。代理程式只能發布到你已連結的帳戶。
供 AI Agent 節點使用的 聊天模型憑證（Anthropic、OpenAI 等）。
(選用) 若你打算透過子設定檔管理多個客戶，則需要 Business 或 Enterprise 方案。

設定 MCP Client Tool 節點

新增 AI Agent 節點

開啟或建立一個工作流程，然後新增 AI Agent 節點（位於 Advanced AI 節點下）。

掛載 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` 僅提供特定工具）

將 Ayrshare 金鑰加入為 Bearer 憑證

在 Credential 中，建立一個新的 Bearer Auth 憑證，將 Ayrshare API 金鑰貼上作為權杖。n8n 會以 Authorization: Bearer YOUR_API_KEY 的形式送出。儲存之後，n8n 會完成連線並列出全部 27 個工具。

接上聊天模型與系統提示

掛載 Chat Model 子節點並選擇你的模型憑證。為代理程式設定一個明確定義規則的系統提示，例如：

你是一名可以使用 Ayrshare 工具的社群媒體助理。在發布任何內容之前，請一律先呼叫 validate_post 並回報任何問題。只有在驗證通過後才呼叫 create_post。預設發布到使用者指定的平台;若未指明，請詢問使用者。絕不憑空產生媒體 URL;僅使用使用者提供的 URL，若有疑慮請透過 validate_media 確認。

新增觸發器

測試時，Manual Trigger 或 Chat Trigger 最方便。實際上線時，使用任何能啟動該工作流程的方式（排程、Webhook、表單、試算表新增列等）。

請使用 HTTP Streamable，不要使用 SSE。 Ayrshare MCP Server 使用較新的 Streamable HTTP 傳輸方式且為無狀態。n8n 的 SSE 選項已廢除，伺服器會拒絕 SSE 串流。請務必選擇 HTTP Streamable。

工具介面

你的代理程式透過這一個 MCP 節點就能看見全部 27 個工具。你幾乎不需要依名稱直接呼叫;只要描述意圖，代理程式就會自行挑選。領域包括 Posts、History、Analytics、Comments、Messages、Profiles、Media、Generate、Webhooks 與 Errors。完整清單以及每個工具的用途與適用範圍，請參見工具目錄。其中兩個工具在安全性上格外突出：validate_post 使用與 create_post 相同的輸入進行試跑，但不會發布任何內容;explain_error 會將任何 Ayrshare 錯誤碼轉譯為清楚的原因與修正方式，方便代理程式自行診斷。

範例 1：從一則聊天訊息開始，草擬、驗證並發布

這是本整合的「Hello World」。用聊天訊息或表單觸發工作流程，其餘交給代理程式。

觸發器： Chat Trigger（或帶有「我們該發布什麼？」欄位的 Form Trigger）。
給代理程式的提示： 「為我們全新的分析儀表板寫一段友善的推出公告，並發布到 LinkedIn、Facebook 與 Instagram。請先驗證。」

代理程式會自行完成：以你的文案與這三個平台呼叫 validate_post;若 Instagram 提示缺少圖片，它會告知你而不是靜默失敗;驗證通過後呼叫 create_post 並回傳已上線的貼文 URL。因為驗證先行，你能在任何內容公開前先發現問題。

範例 2：自動將新內容跨平台發布

不需要人工操作，就能將某個內容來源轉換為多平台貼文。

觸發器： 針對你部落格 feed 的 RSS Read 節點、來自 CMS 的 Webhook，或 Google Sheets 或 Airtable 中新增的一列。
AI Agent 步驟： 「將這篇文章摘要為一則簡短的社群貼文，附上 2 到 3 個相關主題標籤，然後驗證並發布到 LinkedIn、Facebook 與 Threads。」
可選擇在 create_post 步驟之前加入人工介入審核，讓有人核可後再發布。

你可以借助 recommend_hashtags 取得以資料為基礎的主題標籤;若希望由 Ayrshare 而不是你的聊天模型來草擬文案，也可以使用 generate_post。

範例 3：每週分析摘要

反向執行整個流程：讀取成效並回報。

觸發器： Schedule 節點，例如每週一早上 8 點。
AI Agent 步驟： 「拉取上週 LinkedIn、Instagram 與 Facebook 的帳戶層級分析資料，並依互動量列出前 3 則貼文的摘要。」
代理程式會使用 get_social_network_analytics 取得帳戶層級資料、get_post_analytics 取得單則貼文資料，然後你可以將它的摘要送到 Slack、Gmail 或 Notion 節點。

關於頻率：大多數貼文的絕大部分互動都發生在前 24 小時內，指標也不會每秒更新。每天或每週執行一次的排程就已足夠。請不要每隔幾分鐘就輪詢分析資料，否則會在沒有新資料的情況下觸發流量限制。

代表客戶操作（多租戶）

如果你為多個客戶管理社群媒體，Ayrshare 的設定檔（profiles）可讓一個帳戶發布到多組彼此獨立的已連結帳戶。在 Business 或 Enterprise 方案下，你可以從 n8n 以兩種方式指定客戶：

依連線： 在 MCP Client Tool 節點上加上 Profile-Key 標頭（使用 Multiple Headers 驗證方式，以便同時送出 Authorization 與 Profile-Key）。該節點上的每一次呼叫都會以該客戶的身分執行。適用於一個工作流程只服務一個客戶的情境。
依呼叫： 許多工具接受 profileKey 參數，代理程式可依動作分別設定。當兩者同時存在時，本次呼叫的參數優先生效。適用於一個工作流程在多個客戶之間路由的情境。

若要匯入新客戶，代理程式可以先呼叫 create_profile，再呼叫 generate_jwt_social_linking_url 產生一個受管頁面，讓客戶在該頁面上連結自己的帳戶。憑證不會經過你的工作流程。

發布到 X/Twitter

在 n8n 中，將 MCP Client Tool 節點的 Authentication 切換為 Multiple Headers，並在 Authorization 之外加上兩個 X-Twitter-OAuth1-* 標頭。這是每個 Ayrshare 帳戶的一次性設定，同一組金鑰適用於所有設定檔。對於其他平台（Facebook、Instagram、LinkedIn、YouTube、TikTok 等）則不需要額外的標頭。請參見 Connect & Setup → X/Twitter BYO 憑證。

維持人工介入

MCP 工具讓代理程式非常容易就能發布內容 —— 這也正是你應該對它設下閘門的原因。兩種成本很低的防護：

一律先驗證。 在系統提示中固化「先 validate_post 再 create_post」的規則。驗證不會發布任何內容，並能提早捕捉平台規則違規。
加入審核步驟。 在草稿與發布動作之間插入 n8n 的 Send and Wait for Response（Slack 或電子郵件）節點，讓有人在任何內容上線前先核可。對於已排程的內容，代理程式可以用 update_post 修改等待審核的貼文。

REST 備援方案（無代理程式）

如果你想要一個固定、決定性、不含 LLM 的工作流程，可以略過 MCP，改用 HTTP Request 節點呼叫 REST API：

Method： POST
URL： https://api.ayrshare.com/api/post
Authentication： Header Auth，Authorization: Bearer YOUR_API_KEY

{
  "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 閘道錯誤，因此請務必使用 api.ayrshare.com。）同樣的做法也適用於其他 REST 端點。當工作流程完全可預期、也不需要代理程式做決定時，這就是最合適的方案。

疑難排解

症狀	可能原因	修正方式
工具呼叫回傳 `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 錯誤碼解讀為原因與修正方式。

後續步驟

Connect & Setup

端點、傳輸方式、身分驗證、設定檔定位與 BYO 憑證。

工具目錄

按領域分組的 27 個工具，包含適用範圍與用途。

MCP Server

MCP Server 是什麼，以及它如何對應到 Ayrshare API。

Claude Code 外掛

同一個伺服器，專為 Claude Code 打包。

下載 n8n 起始工作流程

​為什麼使用 MCP 而不是自己寫 API 呼叫

​連接方式

​前置需求

​設定 MCP Client Tool 節點

​工具介面

​範例 1：從一則聊天訊息開始，草擬、驗證並發布

​範例 2：自動將新內容跨平台發布

​範例 3：每週分析摘要

​代表客戶操作（多租戶）

​發布到 X/Twitter

​維持人工介入

​REST 備援方案（無代理程式）

​疑難排解

​後續步驟

Connect & Setup

工具目錄

MCP Server

Claude Code 外掛

為什麼使用 MCP 而不是自己寫 API 呼叫

連接方式

前置需求

設定 MCP Client Tool 節點

工具介面

範例 1：從一則聊天訊息開始，草擬、驗證並發布

範例 2：自動將新內容跨平台發布

範例 3：每週分析摘要

代表客戶操作（多租戶）

發布到 X/Twitter

維持人工介入

REST 備援方案（無代理程式）

疑難排解

後續步驟