> ## 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 بخادم Ayrshare MCP للنشر والجدولة والتحليل عبر 13 شبكة اجتماعية، دون الحاجة إلى كود API لكل منصّة.
export const XByoNotice = () =>
Targeting X/Twitter? Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
X-Twitter-OAuth1-Api-Key — Your API Key (Consumer Key)
X-Twitter-OAuth1-Api-Secret — Your API Key Secret (Consumer Secret)
One-time setup per Ayrshare account. You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do not create a new app per customer.
Not linked yet? See the full setup guide to connect your X account.
Your keys are never logged or stored by Ayrshare.
;
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 من تشغيل الحلقة بأكملها بمفرده: صياغة منشور، والتحقق من صحّته وفق قواعد كل شبكة، ونشره أو جدولته، ثم قراءة التحليلات مرة أخرى.
نظرًا لأن MCP Server عبارة عن نقطة نهاية Streamable HTTP مستضافة، فإنك تتّصل بها باستخدام عقدة **MCP Client Tool** المدمجة في n8n. لا يوجد شيء لاستضافته، ولا كود مخصّص، ولا عقدة مجتمعية لتثبيتها. توجّه عقدة واحدة إلى عنوان URL واحد وسيحصل وكيلك على جميع أدوات وسائل التواصل الاجتماعي الـ 27.
سير العمل الموضّح أعلاه، جاهز للاستيراد: Chat Trigger، وAI Agent، ونموذج محادثة Anthropic، وعقدة Ayrshare MCP المهيّأة مسبقًا مع موجّه النظام الذي يعطي الأولوية للتحقق.
لاستخدامه: في n8n، انتقل إلى **Workflows → Import from file**، واختر ملف JSON، ثم أنشئ بيانات الاعتماد الاثنين اللذَين يتوقعهما (بيانات اعتماد **Bearer Auth** تحمل مفتاح Ayrshare الخاص بك، وبيانات اعتماد **Anthropic API**). تختفي شارتا التحذير بمجرد إرفاق بيانات الاعتماد. تحتاج الحالات المستضافة ذاتيًا إلى وصول صادر إلى `api.ayrshare.com` ومزوّد النموذج الخاص بك.
يغطّي هذا الدليل مسار MCP أولاً من البداية إلى النهاية. إذا كنت تفضّل بناء سير عمل ثابت وغير قائم على وكيل، فهناك [بديل REST قصير](#rest-fallback-no-agent) في النهاية.
## لماذا MCP بدلًا من كتابة استدعاءات API
يمكنك استدعاء REST API الخاص بـ Ayrshare مباشرة من عقدة HTTP Request، وهذا مناسب لسير العمل الثابت والمتوقّع. لكن MCP Server يستحقّ مكانه عندما يكون هناك LLM في الحلقة:
- **الوكيل يختار الأداة.** صِف الهدف ("انشر هذا على قنوات أعمالنا وجدوِل المتابعة يوم الثلاثاء") وسيختار الوكيل بنفسه `validate_post` و`create_post` والمعلمات الصحيحة.
- **التحقق قبل نشر أي شيء.** يُجري `validate_post` تشغيلًا تجريبيًا لمحتواك مقابل قواعد الطول والتنسيق والوسائط لكل منصّة، لذا لا يرسل الوكيل منشورًا سترفضه إحدى الشبكات.
- **استدعاء واحد، شبكات متعدّدة.** يوزّع `create_post` واحد على كل منصّة مرتبطة.
- **تغييرات المنصّات مشكلة Ayrshare.** عندما تغيّر إحدى الشبكات واجهة API الخاصة بها، تتولّى Ayrshare صيانة التكامل ويستمرّ سير عملك بالعمل.
- **نفس القواعد الموجودة في REST API.** كل استدعاء لأداة MCP يتم داخل العملية عبر سلسلة API نفسها الخاصة بـ Ayrshare: نفس المصادقة وحدود المعدّل والحصّة والتحقق. لا يوجد سلوك منفصل لتعلّمه.
## كيف يتّصل
عقدة **AI Agent** هي الدماغ. تُرفَق العقدة الفرعية **MCP Client Tool** بها، وتتّصل بخادم Ayrshare MCP على `https://api.ayrshare.com/mcp`، وتكتشف الأدوات المتاحة، وتعرضها للوكيل. عندما يتصرّف الوكيل، ترسل العقدة الاستدعاء إلى Ayrshare، الذي يقوم بالنشر إلى الشبكات.
```
Trigger -> AI Agent (+ Chat Model) -> MCP Client Tool -> Ayrshare MCP Server -> 13 networks
```
للاطلاع على تفاصيل نقطة النهاية والنقل والمصادقة، راجع [Connect & Setup](/additional/mcp-action-connect). للاطلاع على قائمة الأدوات الكاملة، راجع [كتالوج الأدوات](/additional/mcp-action-tools).
## المتطلبات المسبقة
- **حالة n8n** (Cloud أو مستضافة ذاتيًا) في إصدار حديث يحتوي على عقدتَي AI Agent وMCP Client Tool. عقدة MCP Client Tool مدمجة. لا تحتاج إلى عقدة مجتمعية لأن خادم Ayrshare يتحدّث Streamable HTTP.
- **حساب Ayrshare ومفتاح API** (Dashboard → Settings → API Key)، أو ابدأ [تجربة مجانية](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h).
- **حساب اجتماعي واحد على الأقل مرتبط** في Ayrshare. يمكن للوكيل النشر فقط حيث تكون قد ربطت.
- **بيانات اعتماد نموذج محادثة** لعقدة AI Agent (Anthropic أو OpenAI وغيرها).
- *(اختياري)* **Business أو Enterprise plan** إذا كنت ستدير عملاء متعدّدين عبر الملفات الشخصية الفرعية.
## إعداد عقدة MCP Client Tool
افتح أو أنشئ سير عمل وأضف عقدة **AI Agent** (ضمن عُقد *Advanced AI*).
في عقدة AI Agent، انقر على موصّل **Tool** وأضِف عقدة **MCP Client Tool**. اضبطها:
| الحقل | القيمة |
| -------------------- | ------------------------------------------- |
| **Endpoint** | `https://api.ayrshare.com/mcp` |
| **Server Transport** | `HTTP Streamable` |
| **Authentication** | `Bearer Auth` |
| **Tools to Include** | `All` (أو `Selected` لعرض أدوات محدّدة فقط) |
لـ **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 الحديث وهو عديم الحالة. خيار SSE في n8n مهجور، والخادم يرفض تدفّق SSE. اختر دائمًا **HTTP Streamable**.
## سطح الأدوات
يرى وكيلك جميع الأدوات الـ 27 من خلال عقدة MCP الواحدة. نادرًا ما تستدعيها بالاسم؛ فأنت تصف النيّة ويقوم الوكيل بالاختيار. المجالات هي Posts وHistory وAnalytics وComments وMessages وProfiles وMedia وGenerate وWebhooks وErrors. للاطلاع على القائمة الكاملة مع غرض ونطاق كل أداة، راجع [كتالوج الأدوات](/additional/mcp-action-tools).
اثنتان تتميّزان من حيث الأمان: **`validate_post`** يقوم بتشغيل تجريبي لمنشور بنفس مدخلات `create_post` لكنه لا ينشر شيئًا، و\*\*`explain_error`\*\* يحوّل أي رمز خطأ من Ayrshare إلى سبب وحلّ بالإنجليزية البسيطة، حتى يتمكّن الوكيل من التشخيص الذاتي.
## المثال 1: صياغة والتحقق والنشر من رسالة محادثة
"مرحبًا بالعالم" لهذا التكامل. شغّل سير العمل برسالة محادثة أو نموذج، ودع الوكيل يقوم بالباقي.
- **المشغّل:** Chat Trigger (أو Form Trigger مع حقل "ما الذي يجب أن ننشره؟").
- **الموجّه للوكيل:** *"اكتب إعلان إطلاق ودّي للوحة تحليلاتنا الجديدة وانشره على LinkedIn وFacebook وInstagram. تحقّق أولًا."*
ما يفعله الوكيل بمفرده: يستدعي `validate_post` مع نصّك والمنصّات الثلاث؛ إذا أشار Instagram إلى صورة مفقودة فإنه يخبرك بدلاً من الفشل بصمت؛ وبمجرد نجاح التحقق يستدعي `create_post` ويعيد عناوين URL للمنشورات المباشرة. لأن التحقق يتم أولًا، ستعرف بأي مشكلة قبل أن يصبح أي شيء علنيًا.
## المثال 2: نشر تلقائي للمحتوى الجديد عبر قنواتك
حوّل مصدر محتوى إلى منشورات متعدّدة الشبكات دون لمسه.
- **المشغّل:** عقدة RSS Read على تغذية المدوّنة الخاصة بك، أو webhook من نظام إدارة المحتوى (CMS)، أو صف جديد في Google Sheets أو Airtable.
- **خطوة AI Agent:** *"لخّص هذا المقال في منشور اجتماعي قصير مع 2 إلى 3 هاشتاغات ذات صلة، ثم تحقّق وانشر على LinkedIn وFacebook وThreads."*
- يمكنك اختياريًا إضافة موافقة [بشرية في الحلقة](#keep-a-human-in-the-loop) قبل خطوة `create_post` بحيث يوقّع شخص ما.
يمكنك الاعتماد على `recommend_hashtags` للحصول على وسوم مستندة إلى البيانات و`generate_post` إذا كنت تريد أن يصوغ Ayrshare النص بدلًا من نموذج المحادثة الخاص بك.
## المثال 3: ملخّص أسبوعي للتحليلات
قم بتشغيل الحلقة عكسيًا: اقرأ الأداء وأبلغ عنه.
- **المشغّل:** عقدة Schedule، على سبيل المثال كل يوم اثنين في الساعة 8 صباحًا.
- **خطوة AI Agent:** *"اسحب تحليلات الحسابات للأسبوع الماضي لـ LinkedIn وInstagram وFacebook، ولخّص أفضل 3 منشورات حسب التفاعل."*
- يستخدم الوكيل `get_social_network_analytics` للأرقام على مستوى الحساب و`get_post_analytics` للمنشورات الفردية، ثم توجّه ملخّصه إلى عقدة **Slack** أو **Gmail** أو **Notion**.
ملاحظة حول التكرار: تحصل معظم المنشورات على معظم تفاعلها في أول 24 ساعة، ولا يتم تحديث المقاييس ثانية بثانية. جدول يومي أو أسبوعي كافٍ. لا تستفتِ التحليلات كل بضع دقائق وإلا ستصطدم بحدود المعدّل بدون بيانات جديدة.
## التصرّف نيابةً عن العملاء (متعدّد المستأجرين)
إذا كنت تدير وسائل التواصل الاجتماعي لعملاء متعدّدين، فإن ملفات Ayrshare الشخصية تتيح لحساب واحد النشر إلى مجموعات مختلفة عديدة من الحسابات المرتبطة. في Business أو Enterprise plan لديك طريقتان لاستهداف عميل من n8n:
- **لكل اتصال:** أضف رأس `Profile-Key` إلى عقدة MCP Client Tool (استخدم مصادقة **Multiple Headers** حتى تتمكّن من إرسال كل من `Authorization` و`Profile-Key`). عندها يتصرّف كل استدعاء على تلك العقدة كذلك العميل. جيّد عندما يخدم سير عمل عميلًا واحدًا.
- **لكل استدعاء:** تقبل العديد من الأدوات وسيطًا `profileKey`، الذي يمكن للوكيل تعيينه لكل إجراء. عندما يكون كلاهما موجودًا، [يفوز الوسيط في الاستدعاء](/additional/mcp-action-connect#precedence-argument-wins-over-header). جيّد عندما يوجّه سير عمل واحد عبر عملاء متعدّدين.
لتضمين عميل جديد، يمكن للوكيل استدعاء `create_profile` ثم `generate_jwt_social_linking_url` لإنشاء صفحة مستضافة يقوم فيها العميل بربط حساباته الخاصة. لا تمرّ أي بيانات اعتماد عبر سير عملك.
## النشر إلى X/Twitter
في n8n، غيّر **Authentication** في عقدة MCP Client Tool إلى **Multiple Headers** وأضف رأسي `X-Twitter-OAuth1-*` جنبًا إلى جنب مع `Authorization`. إنه إعداد لمرة واحدة لكل حساب Ayrshare، ويسري زوج المفاتيح نفسه على كل ملف شخصي. لكل شيء آخر (Facebook وInstagram وLinkedIn وYouTube وTikTok وغيرها) لا حاجة إلى رؤوس إضافية. راجع [Connect & Setup → X/Twitter BYO credentials](/additional/mcp-action-connect#xtwitter-byo-credentials).
## أبقِ شخصًا في الحلقة
تجعل أدوات MCP من السهل جدًا على الوكيل النشر، وهذا بالضبط سبب وجوب تقييده. حاجزان رخيصان:
- **تحقّق دائمًا أولًا.** أدرج "استدعِ `validate_post` قبل `create_post`" في موجّه النظام. لا ينشر التحقق شيئًا ويكشف انتهاكات قواعد المنصّة مبكرًا.
- **أضف خطوة موافقة.** أدخل عقدة **Send and Wait for Response** (Slack أو بريد إلكتروني) من n8n بين المسودة وإجراء النشر بحيث يوافق شخص قبل نشر أي شيء. للمحتوى المجدول، يمكن للوكيل استخدام `update_post` لتعديل منشور في انتظار الموافقة.
## بديل REST (بدون وكيل)
إذا كنت تريد سير عمل ثابتًا وحتميًا بدون LLM، تجاوز MCP واستدعِ REST API بعقدة **HTTP Request**:
- **Method:** `POST`
- **URL:** `https://api.ayrshare.com/api/post`
- **Authentication:** Header Auth، `Authorization: Bearer YOUR_API_KEY`
```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 الأخرى في [REST endpoints](/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 مفقودة | أضف رأسي `X-Twitter-OAuth1-*` عبر مصادقة Multiple Headers. |
| يفشل المنشور لمنصّة واحدة فقط | تلك الشبكة غير مرتبطة أو حقل مطلوب مفقود | اربطها في لوحة التحكم؛ أضف `title` لـ YouTube، و`title` + `subreddit` لـ Reddit، و`mediaUrls` لـ Instagram. |
| رفض منشور Instagram | لا وسائط | يتطلّب Instagram `mediaUrls` لمعظم أنواع المنشورات. اطلب من الوكيل التأكيد باستخدام `validate_media`. |
| الوسائط المرفقة كملف أو ثنائي لا تظهر | MCP يقبل JSON فقط | أشِر إلى الوسائط عبر عنوان URL عام في `mediaUrls`؛ لا يقبل مسار MCP رفع الملفات. أكّد عنوان URL باستخدام `validate_media`. |
| تعمل الاستدعاءات ولكن تتصرّف على العميل الخطأ | استهداف الملف الشخصي | عيّن رأس `Profile-Key` (لكل اتصال) أو وسيط `profileKey` (لكل استدعاء)؛ يفوز الوسيط إذا تم تعيين كليهما. |
| `429 Too Many Requests` | استفتاء متكرّر جدًا | قلّل تكرار استفتاء التحليلات والتعليقات؛ لا يتم تحديث المقاييس ثانية بثانية. |
| تغيير التكوين لم يسرِ | تتمّ تهيئة اتصال MCP في بداية الجلسة | أعِد حفظ العقدة أو أعِد تشغيل سير العمل بعد تغيير المفتاح أو الرؤوس. |
يمكنك أيضًا عرض أداة `explain_error` للوكيل لكي يفكّ ترميز أي رمز خطأ من Ayrshare إلى سبب وحلّ بمفرده.
## الخطوات التالية
نقطة النهاية والنقل والمصادقة واستهداف الملف الشخصي وبيانات اعتماد BYO.
الأدوات الـ 27 المجمّعة حسب المجال، مع النطاق والغرض.
ما هو MCP Server وكيف يرتبط بواجهة Ayrshare API.
الخادم نفسه، معبَّأ لأجل Claude Code.