شنو كيدير whatsapp-mcp
whatsapp-mcp هو سيرفر صغير كيخلّي واحد العميل ديال الذكاء الاصطناعي المتوافق مع MCP يقرا ويقلّب فالرسايل ديال WhatsApp ديالك. كيخدم فحساب Cloudflare ديالك وكيترابط مع تيليفونك بحال جهاز مربوط على طريقة WhatsApp Web.
من بعد الإعداد الأولي، العملاء بحال Claude Code وClaude Desktop ولا تطبيقات MCP خرين يقدرو يجاوبو على أسئلة بحال:
- شنو قال Dana على الرحلات الجوية؟
- قلّب على كل رسالة فيها ذكر للكراء فگاع المحادثات.
- لخّص ليا شنو فاتني فگروب العائلة هاد السيمانة.
السيرفر معمول عمداً غير للقراية: يقدر يجمع الرسايل ويقلّب فيها ويعرضها، ولكن ما يقدرش يصيفط رسايل WhatsApp.
كيفاش كيخدم السيستيم
تيليفونك كيبقى هو المصدر الأساسي ديال الحقيقة. النشر فـ Cloudflare كيخدم كجهاز مربوط وكيترابط مع WhatsApp غير ملي كيحتاج يزامن المعطيات ولا ملي كتربط الحساب.
ملي كيطلب العميل معلومات، السيرفر كيجبد التحديثات اللي كاتسناه من WhatsApp إلا كانت النسخة المخزنة عندو قديمة بأكثر من عشر دقايق. كاين حتى جلب مبرمج كيتشغل مرة فالنهار. من بعد ما كيجمع الرسايل، السيرفر كينقطع من جديد. تيليفونك كيبقى خدام عادي وكيستمر فاستقبال الإشعارات.
الرسايل كاتخزن فقاعدة بيانات SQLite داخل Cloudflare Durable Object فالحساب ديالك. السيرفر ما كيصيفطش سجل الرسايل ديالك لخدمة تخزين خارجية.
المتطلبات
قبل التثبيت، وجد هاد الحوايج:
- حساب Cloudflare فـ Workers Paid plan.
- Node.js 20 ولا أحدث.
- تيليفون فيه حساب WhatsApp اللي بغيتي تربط.
- عميل MCP، بحال Claude Code ولا Claude Desktop.
الخطة المدفوعة ديال Workers مهمة حيث استيراد سجل كبير ديال WhatsApp يقدر يفوت الحد الافتراضي ديال CPU. المستودع كيرفع هاد الحد فـ wrangler.jsonc، وCloudflare كاتطلب الخطة المدفوعة باش تستعمل الحد الأعلى.
التثبيت والنشر
نسخ المستودع، ثبّت الاعتماديات ديالو، أنشئ مساحة KV المطلوبة، خزّن كلمة سر المالك، ونشّر الـ Worker:
git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install
npx wrangler kv namespace create OAUTH_KV
npx wrangler secret put OWNER_PASSWORD
npm run deployخاص كلمة السر تكون فيها على الأقل 12 حرف. ملي يسالي النشر، Wrangler كيطبع رابط بحال https://whatsapp-mcp.your-name.workers.dev. حل داك الرابط باش تكمل الإعداد.
إلا بغيتي تستعمل دومين مخصص، تبع التعليقات اللي فآخر wrangler.jsonc.
ربط حساب WhatsApp ديالك
صفحة النشر كاتعطيك الخطوات الباقية ديال الإعداد.
- ختار الخيار ديال ربط WhatsApp.
- حل WhatsApp فتيليفونك ومشِ لـ Settings، ومن بعد Linked Devices، ومن بعد Link a Device.
- سكانِي رمز QR اللي كيبينو السيرفر. إلا كنت كتستعمل نفس التيليفون وما قادرش تسكاني الشاشة ديالو، استعمل خيار الربط برقم التيليفون عوض ذلك.
- تسنى حتى يكمل الربط الأول استيراد السجل اللي كاتوفرو WhatsApp لجهاز جديد مربوط.
الصفحة كاتبيّن تقدم الاستيراد، وتقدر تسدها والعملية غاتبقى مستمرة. الاستيراد الأولي ممكن ما يشملش كل الرسايل القديمة حيث WhatsApp هو اللي كيقرر شنو من السجل يعطي لجهاز مربوط جديد.
ربط عميل MCP
فـ Claude Code، سجّل السيرفر المنشور باستعمال نقطة النهاية /mcp ديالو:
claude mcp add --transport http whatsapp https://your-url/mcpمن بعد شغّل /mcp فـ Claude Code ودخل بكلمة سر المالك. العملاء الآخرين ديال MCP خاصهم يتضبطو بنفس الرابط:
https://your-url/mcpمنين يتم التحقق، طلب من العميل يعرض المحادثات، يجيب الرسايل، ولا يقلّب فالسجل ديالك.
استعمل الأدوات المتوفرة
سيرفر MCP كيوفر أدوات مركزة لقراية النسخة المحلية ديال الرسايل وصيانتها:
list_chatsكيعرض المحادثات، من الأحدث للأقدم، مع إمكانية التصفية بالاسم ولا بالرقم.get_messagesكيقرا الرسايل من محادثة وحدة وكيخدم بالتنقل للور ولا للقدام حسب التاريخ.search_messagesكيدير بحث بالنص الكامل فگاع المحادثات ولا داخل محادثة مختارة.unnamed_chatsكيلقا المحادثات اللي معروفة غير برقم التيليفون، وكيعطي الأولوية للمحادثات الأكثر نشاطاً وكيبيّن آخر رسالة من الشخص الآخر.set_contact_namesكيحفظ الأسامي ديال أرقام التيليفون باش يقدرو يبانوا حتى فگروبات المحادثة.sync_nowكيجلب الرسايل الجديدة دابا.link_statusكيعطي واش الحساب مربوط، وفاش تزامن آخر مرة، وشحال من المعطيات مخزنة.relinkكيحيد الربط الحالي وكيبدا عملية الربط من جديد. الرسايل المخزنة كاتبقى متوفرة.
أدوات القراية كاتزامن أوتوماتيكياً قبل ما تخدم إلا كانت النسخة المخزنة قديمة بأكثر من عشر دقايق. بهاد الطريقة تقدر تستعمل طلبات باللغة الطبيعية بلا ما تعيط يدوياً على sync_now مع كل سؤال.
حلّ المحادثات اللي كاتبان غير بأرقام التيليفون
شي محادثات كاتبان بأرقام التيليفون حيث WhatsApp ما كيعطيش اسم جهة الاتصال لكل جهاز مربوط. هاد الشي شائع فالمحادثات العابرة ولا مع الناس اللي ما محفوظينش فجهات الاتصال ديال WhatsApp ديالك.
طلب من العميل:
Find names for my unnamed chats.العميل يقدر يعيط على unnamed_chats، يقارن الأرقام مع تكامل جهات الاتصال اللي متوفر عندو، ويصيفط المطابقات باستعمال set_contact_names. مثلاً، رابط Google Contacts ولا Gmail يقدر يوفر الأسامي المطابقة. السيرفر براسو ما كيدخلش لخدمة ديال جهات الاتصال.
الأسامي المحفوظة كاترتابط برقم التيليفون، وبالتالي تقدر تستعمل حتى فالمحادثات الجماعية. بعض الأرقام غاتبقى بلا اسم إلا ما كان حتى جهة اتصال مطابقة.
فهم تاريخ الوسائط والرسائل
ملفات الوسائط ما كيتحمّلوش. الصور، الرسائل الصوتية، والوثائق كيتعرّفو بعلامات بحال [image] ولا [voice note 12s]. التعاليق كيبقاو محفوظين إلا كان واتساب كيوفّرهم، ولكن الرسائل الصوتية ما كيتدارش ليها التفريغ النصي.
أول ربط كيستورد أي تاريخ كيختار واتساب يرسلو. عادةً التاريخ كيتبعث مرة وحدة مع كل رابط. إلا كان الاستيراد ناقص، تقدر تعاود الربط باش تطلب استيراد آخر، مع الاحتفاظ بالرسائل اللي تخزنو من قبل. عملية الإدخال مصممة تكون آمنة من التكرار، يعني إعادة الاستيراد ما كتخلقش عمداً صفوف مكررة.
عاود ربط الحساب
عاود الربط إلا قال واتساب باللي الجهاز تحيّد، ولا إلا بغيتي تبدا عملية الربط من جديد. طلب من الوكيل ديالك يشغّل relink، ولا حلّ /setup واختار Unlink and scan again.
سكانّي رمز QR الجديد ملي يطلب منك النظام. الرسائل المخزنة من قبل كتبقى، والرابط الجديد يقدر يعمّر التاريخ الناقص.
الإعدادات المتقدمة
النشر الافتراضي كيستعمل المصادقة بكلمة السر. أهم قيم الإعداد كتضم:
OWNER_PASSWORD: كلمة سر المالك، وخاصها تكون فيها 12 حرف على الأقل.OWNER_EMAIL: عنوان البريد الإلكتروني الوحيد المسموح به ملي كيكون وضع خدمة تسجيل الدخول مفعّل.OPERATOR_NAME: اسم اختياري كيبان فصفحة الخصوصية.DEFAULT_COUNTRY_CODE: رمز دولة مكوّن غير من الأرقام، كيتستعمل ملي الوكيل كيحفظ رقم بلا رمز دولة.LOGIN_ORIGIN: كينقل النشر لوضع خدمة تسجيل الدخول.ALLOWED_ORIGINS: المصادر المقبولة لرموز خدمة تسجيل الدخول.PIN: قيمة اختيارية فيها 32 حرف أو أكثر، وكتفعّل مسارات تصحيح محمية عبر ترويسةx-pin.OAUTH_KVوWA: روابط KV وDurable Object اللي كيستعملهم التطبيق.
خلي القيم الخاصة بكل نشر، بحال النطاق، ومعرّف KV، والبريد الإلكتروني، فملف wrangler.local.jsonc مضاف لـ gitignore. نشر الإعدادات المحلية بهاد الأمر:
npm run deploy:localصحّح مشاكل المزامنة
إلا ضبطتي PIN، الخادم كيوفّر نقاط نهاية تشخيصية محمية. صيفط PIN فترويسة x-pin:
/debugكيبين مرحلة الجلسة، حالة الربط، الأعداد، وآخر أحداث الجلسة./debug/pullكيبدا المزامنة دابا./debug/chats?q=، و/debug/messages?chat=، و/debug/search?q=، و/debug/typesكيتفقدو البيانات المخزنة./debug/unnamedكيبين المحادثات اللي رجّعهاunnamed_chats./debug/sql?q=كينفّذ استعلامSELECTواحد للقراءة فقط على المخزن./debug/logoutكيدير نفس العملية ديال إعادة الربط.
من بعد نشر ناجح، تسلسل مفيد للتحقق هو تتأكد أن /debug كيبين جلسة خاملة وحساب مربوط، وتشغّل /debug/pull، ومن بعد تجرّب عرض المحادثات، جلب الرسائل، البحث الكامل فالنص، التعامل مع المحادثات بلا اسم، وتسميات جهات الاتصال.
طوّر محلياً
للتطوير المحلي، صايب ملف .dev.vars فيه كلمة سر طويلة بما يكفي وشغّل Worker:
OWNER_PASSWORD=your-12-character-or-longer-password
npm run devالتطوير المحلي كيستعمل Durable Object منفصل بمخزن خاوي. يقدر يجرّب مسار تسجيل الدخول ويعرض رمز QR حقيقي، ولكن ربط الهاتف محلياً كينشئ جهازاً مربوطاً آخر.
قبل ما تصيفط تغييرات الكود، شغّل:
npm run typecheck
npm testمجموعة الاختبارات كتشغّل كود التخزين باستعمال SQLite المدمج فـ Node على Node 22.13 أو أحدث. البحث الكامل فالنص ما مغطّاش فبيئة SQLite هادي، لذلك جرّب البحث من بعد النشر حتى هو.
اعتبارات مهمة ديال الأمان والمنصة
هاد المشروع ماشي تكامل رسمي مع واتساب. واتساب ما كيوفّرش API لقراءة الرسائل الشخصية، وهاد المشروع كيستعمل نفس البروتوكول ديال WhatsApp Web عبر مكتبة Baileys مفتوحة المصدر. هاد الاستعمال يقدر يخرق شروط واتساب. استعملو غير مع الحساب ديالك، وخذ بعين الاعتبار أن الخطر العملي منخفض بالنسبة لجهاز مربوط للقراءة فقط، ولكن ماشي منعدم.
كل نشر مخصص لشخص واحد وحساب واتساب واحد. كل نشر كيخزّن تاريخ الرسائل كامل وتسجيل دخول حي للحساب، لذلك خاص المستخدمين يديرو نشرات منفصلة وما يتشاركوش نشراً واحداً.
الرسائل كتبقى داخل تخزين SQLite ديال Durable Object، ولكن أي واحد يقدر يوصل لبيانات اعتماد النشر أو لمصادقة المالك يقدر يوصل للتاريخ المخزن. حمي كلمة السر، وحساب Cloudflare، والأسرار، وأي PIN ديال التصحيح بعناية.
الخلاصة
whatsapp-mcp كيوفّر جسراً عملياً بين بروتوكول الأجهزة المربوطة ديال واتساب وعملاء MCP. نشرو فـ Cloudflare، ربط الهاتف ديالك مرة وحدة، ربط وكيل بـ /mcp، واستعمل أدوات بحال search_messages، وget_messages، وset_contact_names باش تستكشف أرشيف الرسائل ديالك. التصميم ديالو للقراءة فقط، والتخزين الخاص فـ Durable Object، والمزامنة المجدولة، ومسار إعادة الربط الواضح، كيخليوه مناسب للبحث فالرسايل الشخصية مع بقاء النشر تحت السيطرة ديالك.