whatsapp-mcp کے ساتھ نجی WhatsApp پیغام تلاش سرور بنائیں

whatsapp-mcp کیا کرتا ہے

whatsapp-mcp ایک چھوٹا سرور ہے جو MCP سے مطابقت رکھنے والے AI ایجنٹ کو آپ کے WhatsApp پیغامات پڑھنے اور تلاش کرنے کی سہولت دیتا ہے۔ یہ آپ کے اپنے Cloudflare اکاؤنٹ میں چلتا ہے اور WhatsApp Web جیسے منسلک ڈیوائس کے طور پر آپ کے فون سے جڑتا ہے۔

ابتدائی سیٹ اپ کے بعد، Claude Code، Claude Desktop یا دیگر MCP ایپلیکیشنز جیسے کلائنٹس ایسے سوالات کے جواب دے سکتے ہیں:

• پروازوں کے بارے میں Dana نے کیا کہا؟
• تمام چیٹس میں لیز کا ذکر کرنے والا ہر پیغام تلاش کریں۔
• اس ہفتے فیملی گروپ میں جو کچھ مجھ سے رہ گیا، اس کا خلاصہ دیں۔

سرور کو جان بوجھ کر صرف پڑھنے کے لیے بنایا گیا ہے: یہ پیغامات جمع، تلاش اور دکھا سکتا ہے، لیکن WhatsApp پیغامات بھیج نہیں سکتا۔

سسٹم کیسے کام کرتا ہے

آپ کا فون معلومات کا بنیادی ماخذ رہتا ہے۔ Cloudflare deployment ایک منسلک ڈیوائس کے طور پر کام کرتا ہے اور WhatsApp سے صرف اس وقت جڑتا ہے جب اسے ڈیٹا ہم وقت ساز کرنے یا اکاؤنٹ جوڑنے کی ضرورت ہو۔

جب کوئی ایجنٹ معلومات طلب کرتا ہے تو اگر سرور میں محفوظ نقل دس منٹ سے زیادہ پرانی ہو، سرور WhatsApp سے زیرِ التوا اپ ڈیٹس حاصل کرتا ہے۔ ایک scheduled pull بھی روزانہ ایک بار چلتا ہے۔ پیغامات حاصل کرنے کے بعد سرور دوبارہ منقطع ہو جاتا ہے۔ آپ کا فون معمول کے مطابق کام کرتا رہتا ہے اور اطلاعات وصول کرتا رہتا ہے۔

پیغامات آپ کے اکاؤنٹ میں موجود Cloudflare Durable Object کے اندر SQLite database میں محفوظ ہوتے ہیں۔ سرور آپ کی پیغاماتی تاریخ کسی بیرونی storage service کو نہیں بھیجتا۔

ضروریات

انسٹال کرنے سے پہلے درج ذیل تیار رکھیں:

• Workers Paid plan والا Cloudflare اکاؤنٹ۔
• Node.js 20 یا اس کے بعد کا ورژن۔
• وہ فون جس پر موجود WhatsApp اکاؤنٹ کو آپ جوڑنا چاہتے ہیں۔
• ایک MCP کلائنٹ، جیسے Claude Code یا Claude Desktop۔

Paid Workers plan اہم ہے کیونکہ WhatsApp کی بڑی تاریخ درآمد کرنے سے CPU کی طے شدہ حد سے تجاوز ہو سکتا ہے۔ repository wrangler.jsonc میں یہ حد بڑھاتی ہے، اور Cloudflare زیادہ حد کے لیے paid plan کا تقاضا کرتا ہے۔

انسٹال اور deploy کریں

repository کو clone کریں، اس کی dependencies انسٹال کریں، مطلوبہ KV namespace بنائیں، owner password محفوظ کریں، اور Worker deploy کریں:

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 حروف کا ہونا چاہیے۔ deployment مکمل ہونے پر Wrangler https://whatsapp-mcp.your-name.workers.dev جیسا URL دکھاتا ہے۔ سیٹ اپ جاری رکھنے کے لیے وہ URL کھولیں۔

اگر آپ custom domain استعمال کرنا چاہتے ہیں تو wrangler.jsonc کے آخر میں موجود تبصروں پر عمل کریں۔

اپنا WhatsApp اکاؤنٹ جوڑیں

deployment صفحہ سیٹ اپ کے باقی مراحل فراہم کرتا ہے۔

1. WhatsApp جوڑنے کا اختیار منتخب کریں۔
2. اپنے فون پر WhatsApp کھولیں اور Settings، Linked Devices، پھر Link a Device پر جائیں۔
3. سرور کی جانب سے دکھایا گیا QR code اسکین کریں۔ اگر آپ وہی فون استعمال کر رہے ہیں اور اس کی اسکرین اسکین نہیں کر سکتے تو فون نمبر کے ذریعے pairing کا اختیار استعمال کریں۔
4. انتظار کریں جب تک پہلا link اس تاریخ کو درآمد نہ کر لے جو WhatsApp نئے ڈیوائس کے لیے دستیاب کرتا ہے۔

صفحہ درآمد کی پیش رفت دکھاتا ہے، اور عمل جاری رہنے کے دوران آپ اسے بند کر سکتے ہیں۔ ابتدائی درآمد میں ہر تاریخی پیغام شامل نہیں ہو سکتا، کیونکہ WhatsApp فیصلہ کرتا ہے کہ نئے منسلک ڈیوائس کو کتنی تاریخ فراہم کرنی ہے۔

MCP کلائنٹ سے جڑیں

Claude Code میں deployed سرور کو اس کے /mcp endpoint کے ساتھ رجسٹر کریں:

claude mcp add --transport http whatsapp https://your-url/mcp

پھر Claude Code میں /mcp چلائیں اور owner password سے سائن اِن کریں۔ دیگر MCP کلائنٹس کو اسی URL کے ساتھ configure کرنا چاہیے:

https://your-url/mcp

تصدیق کے بعد ایجنٹ سے چیٹس کی فہرست بنانے، پیغامات حاصل کرنے یا اپنی تاریخ تلاش کرنے کو کہیں۔

دستیاب tools استعمال کریں

MCP سرور مقامی پیغامات کی نقل پڑھنے اور برقرار رکھنے کے لیے مخصوص tools فراہم کرتا ہے:

• list_chats چیٹس کو تازہ ترین پہلے دکھاتا ہے، اور نام یا نمبر کے اختیاری فلٹر کے ساتھ۔
• get_messages ایک چیٹ کے پیغامات پڑھتا ہے اور تاریخ کے لحاظ سے پیچھے یا آگے paging کو سپورٹ کرتا ہے۔
• search_messages تمام چیٹس میں یا منتخب چیٹ کے اندر full-text تلاش کرتا ہے۔
• unnamed_chats ایسی چیٹس تلاش کرتا ہے جو صرف فون نمبر سے معلوم ہوں، سب سے زیادہ فعال چیٹس کو ترجیح دیتا ہے اور دوسرے شخص کا تازہ ترین پیغام دکھاتا ہے۔
• set_contact_names فون نمبروں کے لیے نام محفوظ کرتا ہے تاکہ وہ گروپ چیٹس میں بھی درست طور پر ظاہر ہو سکیں۔
• sync_now نئے پیغامات فوراً حاصل کرتا ہے۔
• link_status بتاتا ہے کہ اکاؤنٹ منسلک ہے یا نہیں، آخری بار کب ہم وقت ساز ہوا، اور کتنا ڈیٹا محفوظ ہے۔
• relink موجودہ link ہٹا کر pairing کا عمل دوبارہ شروع کرتا ہے۔ محفوظ شدہ پیغامات دستیاب رہتے ہیں۔

اگر محفوظ شدہ نقل دس منٹ سے زیادہ پرانی ہو تو پڑھنے والے tools پہلے خودکار طور پر ہم وقت سازی کرتے ہیں۔ اس لیے ہر سوال کے لیے sync_now کو دستی طور پر چلائے بغیر قدرتی زبان میں درخواستیں کی جا سکتی ہیں۔

صرف فون نمبر کے طور پر ظاہر ہونے والی چیٹس حل کریں

کچھ چیٹس فون نمبروں کے طور پر ظاہر ہوتی ہیں کیونکہ WhatsApp ہر منسلک ڈیوائس کو رابطے کا نام فراہم نہیں کرتا۔ یہ یک بار ہونے والی گفتگو یا ایسے لوگوں کے لیے عام ہے جو آپ کے WhatsApp contacts میں محفوظ نہیں ہیں۔

اپنے ایجنٹ سے کہیں:

Find names for my unnamed chats.

ایجنٹ unnamed_chats چلا سکتا ہے، نمبروں کا اپنے پاس موجود contacts integration سے موازنہ کر سکتا ہے، اور set_contact_names کے ذریعے مماثل نام بھیج سکتا ہے۔ مثال کے طور پر Google Contacts یا Gmail connector مماثل نام فراہم کر سکتا ہے۔ سرور خود کسی contacts service میں login نہیں کرتا۔

محفوظ کیے گئے نام فون نمبر سے منسلک ہوتے ہیں، اس لیے انہیں گروپ گفتگو میں بھی استعمال کیا جا سکتا ہے۔ جب کوئی مماثل contact موجود نہ ہو تو کچھ نمبر نام کے بغیر رہیں گے۔

میڈیا اور پیغامات کی سرگزشت کو سمجھیں

میڈیا فائلیں ڈاؤن لوڈ نہیں کی جاتیں۔ تصاویر، صوتی نوٹس اور دستاویزات کو [image] یا [voice note 12s] جیسے لیبلز سے ظاہر کیا جاتا ہے۔ جب WhatsApp کیپشن فراہم کرتا ہے تو انہیں محفوظ رکھا جاتا ہے، لیکن صوتی پیغامات کو تحریر میں تبدیل نہیں کیا جاتا۔

پہلا لنک وہ تمام سرگزشت درآمد کرتا ہے جسے WhatsApp بھیجنے کا انتخاب کرتا ہے۔ سرگزشت عموماً ہر لنک کے لیے ایک بار فراہم کی جاتی ہے۔ اگر درآمد نامکمل ہو تو دوبارہ لنک کرنے سے ایک اور درآمد کی درخواست کی جا سکتی ہے، جبکہ پہلے سے محفوظ پیغامات برقرار رہتے ہیں۔ Ingest کو idempotent بنانے کے لیے ڈیزائن کیا گیا ہے، اس لیے دوبارہ درآمد کرنے سے جان بوجھ کر نقل قطاریں نہیں بنتیں۔

اکاؤنٹ دوبارہ لنک کریں

اگر WhatsApp اطلاع دے کہ ڈیوائس ہٹا دی گئی ہے، یا آپ جوڑا بنانے کا عمل دوبارہ شروع کرنا چاہتے ہیں، تو دوبارہ لنک کریں۔ اپنے ایجنٹ سے relink چلانے کو کہیں، یا /setup کھولیں اور Unlink and scan again منتخب کریں۔

اشارہ ملنے پر نیا QR کوڈ اسکین کریں۔ پہلے سے محفوظ پیغامات برقرار رہتے ہیں، جبکہ نیا لنک گم شدہ سرگزشت مکمل کر سکتا ہے۔

اعلیٰ درجے کی تشکیل

پہلے سے طے شدہ deployment میں پاس ورڈ سے توثیق استعمال ہوتی ہے۔ اہم configuration اقدار میں شامل ہیں:

• OWNER_PASSWORD: مالک کا پاس ورڈ، جس کی کم از کم لمبائی 12 حروف ہے۔
• OWNER_EMAIL: login-service mode استعمال ہونے پر واحد مجاز ای میل پتہ۔
• OPERATOR_NAME: privacy page پر دکھایا جانے والا اختیاری نام۔
• DEFAULT_COUNTRY_CODE: صرف ہندسوں پر مشتمل ملک کا کوڈ، جو ایجنٹ کے بغیر کوڈ کے نمبر محفوظ کرنے پر استعمال ہوتا ہے۔
• LOGIN_ORIGIN: deployment کو login-service mode میں تبدیل کرتا ہے۔
• ALLOWED_ORIGINS: login-service tokens کے لیے قابل قبول origins۔
• PIN: اختیاری 32 یا اس سے زیادہ حروف کی قدر، جو x-pin header کے ذریعے محفوظ debug routes فعال کرتی ہے۔
• OAUTH_KV اور WA: ایپلیکیشن کے زیر استعمال KV اور Durable Object bindings۔

deployment سے متعلق اقدار، جیسے domain، KV ID اور ای میل، کو gitignored wrangler.local.jsonc فائل میں رکھیں۔ مقامی configuration کو اس کمانڈ سے deploy کریں:

npm run deploy:local

ہم وقتی مسائل کی تشخیص کریں

اگر آپ PIN configure کرتے ہیں تو سرور محفوظ تشخیصی endpoints فراہم کرتا ہے۔ PIN کو x-pin header میں بھیجیں:

• /debug session phase، link state، counts اور حالیہ session events دکھاتا ہے۔
• /debug/pull فوراً synchronization شروع کرتا ہے۔
• /debug/chats?q=، /debug/messages?chat=، /debug/search?q= اور /debug/types محفوظ شدہ ڈیٹا کا جائزہ لیتے ہیں۔
• /debug/unnamed، unnamed_chats سے واپس آنے والی chats دکھاتا ہے۔
• /debug/sql?q= store کے خلاف ایک صرف پڑھنے والی SELECT query چلاتا ہے۔
• /debug/logout دوبارہ لنک کرنے کے مساوی عمل انجام دیتا ہے۔

کامیاب deployment کے بعد مفید verification sequence یہ ہے کہ جانچیں آیا /debug idle session اور linked account رپورٹ کرتا ہے، پھر /debug/pull چلائیں، اور اس کے بعد chat listing، message retrieval، full-text search، unnamed-chat handling اور contact naming آزمائیں۔

مقامی طور پر develop کریں

مقامی development کے لیے کافی طویل پاس ورڈ پر مشتمل .dev.vars فائل بنائیں اور Worker شروع کریں:

OWNER_PASSWORD=your-12-character-or-longer-password

npm run dev

مقامی development میں خالی storage کے ساتھ الگ Durable Object استعمال ہوتا ہے۔ یہ sign-in flow اور حقیقی QR code دکھانے کی جانچ کر سکتا ہے، لیکن مقامی طور پر فون لنک کرنے سے ایک اور linked device بن جاتی ہے۔

code changes جمع کرانے سے پہلے چلائیں:

npm run typecheck
npm test

test suite Node 22.13 یا اس کے بعد کے ورژن میں Node کے built-in SQLite کے خلاف store code چلاتا ہے۔ اس SQLite environment میں full-text search شامل نہیں ہے، اس لیے deployment کے بعد search کی بھی جانچ کریں۔

اہم سکیورٹی اور پلیٹ فارم سے متعلق امور

یہ project سرکاری WhatsApp integration نہیں ہے۔ WhatsApp ذاتی پیغامات پڑھنے کے لیے API فراہم نہیں کرتا، اور یہ project open-source Baileys library کے ذریعے WhatsApp Web جیسا ہی protocol استعمال کرتا ہے۔ ایسا استعمال WhatsApp کی شرائط کی خلاف ورزی کر سکتا ہے۔ اسے صرف اپنے اکاؤنٹ کے ساتھ استعمال کریں، اور یاد رکھیں کہ read-only linked device کے لیے عملی خطرہ کم ہے، لیکن ختم نہیں ہوتا۔

ایک deployment ایک شخص اور ایک WhatsApp account کے لیے ہے۔ ہر deployment مکمل message history اور live account login محفوظ کرتا ہے، اس لیے صارفین کو ایک deployment بانٹنے کے بجائے الگ الگ deployments چلانے چاہییں۔

پیغامات Durable Object کی SQLite storage کے اندر رہتے ہیں، لیکن جو بھی deployment credentials یا owner authentication تک رسائی حاصل کر لے، وہ محفوظ شدہ سرگزشت تک رسائی حاصل کر سکتا ہے۔ پاس ورڈ، Cloudflare account، secrets اور کسی بھی debug PIN کو احتیاط سے محفوظ رکھیں۔

نتیجہ

whatsapp-mcp، WhatsApp کے linked-device protocol اور MCP clients کے درمیان ایک عملی پل فراہم کرتا ہے۔ اسے Cloudflare پر deploy کریں، اپنے فون کو ایک بار لنک کریں، کسی agent کو /mcp سے مربوط کریں، اور اپنی پیغامات کی سرگزشت تلاش کرنے کے لیے search_messages، get_messages اور set_contact_names جیسے tools استعمال کریں۔ اس کا read-only ڈیزائن، نجی Durable Object storage، scheduled synchronization اور واضح relinking workflow اسے ذاتی پیغامات کی تلاش کے لیے موزوں بناتے ہیں، جبکہ deployment کا اختیار آپ کے پاس رہتا ہے۔