WhatsApp MCP Sunucusu

Bu, WhatsApp için bir Model Context Protocol (MCP) sunucusudur.

Bunu kullanarak kişisel WhatsApp mesajlarınızı (resimler, videolar, belgeler ve ses mesajları dahil) arayabilir ve okuyabilir, kişilerinizi arayabilir ve bireysel kişilere veya gruplara mesaj gönderebilirsiniz. Ayrıca resimler, videolar, belgeler ve ses mesajları dahil medya dosyaları gönderebilirsiniz.

Kişisel WhatsApp hesabınıza doğrudan Whatsapp web çoklu cihaz API'si üzerinden bağlanır (whatsmeow kütüphanesini kullanarak). Tüm mesajlarınız yerel bir SQLite veritabanında saklanır ve yalnızca bir LLM (Claude gibi) tarafından aracılar aracılığıyla erişildiğinde gönderilir (bunu kontrol edersiniz).

Claude'a bağlandığında neler yapabileceğinize dair bir örnek aşağıdadır.

Bu ve üzerinde çalıştığım diğer projeler hakkında güncellemeler almak için buraya e-posta adresinizi girin

Uyarı: birçok MCP sunucusu gibi, WhatsApp MCP de ölümcül üçlüye tabidir. Bu, proje enjeksiyonunun özel veri sızıntısına yol açabileceği anlamına gelir.

Kurulum

Ön Koşullar

• Go
• Python 3.6+
• Anthropic Claude Desktop uygulaması (veya Cursor)
• UV (Python paket yöneticisi), curl -LsSf https://astral.sh/uv/install.sh | sh ile yükleyin
• FFmpeg (isteğe bağlı) - Yalnızca ses mesajları için gereklidir. Ses dosyalarını çalınabilir WhatsApp ses mesajları olarak göndermek istiyorsanız, bunlar .ogg Opus formatında olmalıdır. FFmpeg yüklü olduğunda, MCP sunucusu Opus olmayan ses dosyalarını otomatik olarak dönüştürecektir. FFmpeg olmadan, send_file aracını kullanarak ham ses dosyalarını yine de gönderebilirsiniz.

Adımlar

1. Bu depoyu klonlayın

   git clone https://github.com/lharries/whatsapp-mcp.git
   cd whatsapp-mcp
   

2. WhatsApp köprüsünü çalıştırın

   whatsapp-bridge dizinine gidin ve Go uygulamasını çalıştırın:

   cd whatsapp-bridge
   go run main.go
   

   İlk çalıştırdığınızda, bir QR kodunu taramanız istenecektir. WhatsApp mobil uygulamanızla QR kodunu tarayarak kimlik doğrulama yapın.

   Yaklaşık 20 gün sonra, yeniden kimlik doğrulama yapmanız gerekebilir.

3. MCP sunucusuna bağlanın

   Uygun {{PATH}} değerleriyle aşağıdaki json'u kopyalayın:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}", // `which uv` komutunu çalıştırın ve çıktıyı buraya yapıştırın
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // depoya girin, `pwd` komutunu çalıştırın ve çıktıyı buraya yapıştırın + "/whatsapp-mcp-server"
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Claude için, bunu Claude Desktop yapılandırma dizininizde claude_desktop_config.json olarak kaydedin:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Cursor için, bunu Cursor yapılandırma dizininizde mcp.json olarak kaydedin:

   ~/.cursor/mcp.json
   

4. Claude Desktop / Cursor'u yeniden başlatın

   Claude Desktop'u açın ve artık WhatsApp'i kullanılabilir bir entegrasyon olarak görebilirsiniz.

   Veya Cursor'u yeniden başlatın.

Windows Uyumluluğu

Bu projeyi Windows üzerinde çalıştırıyorsanız, go-sqlite3'ün düzgün şekilde derlenip çalışması için CGO'nun etkinleştirilmesi gerektiğini unutmayın. Varsayılan olarak, Windows'ta CGO devre dışıdır, bu nedenle açıkça etkinleştirmeniz ve bir C derleyicisi yüklemeniz gerekir.

Çalışmaya başlamak için adımlar:

1. Bir C derleyicisi yükleyin
   Windows için bir C derleyicisi yüklemek için MSYS2 kullanmanızı öneririz. MSYS2'yi yükledikten sonra, ucrt64\bin klasörünü PATH'inize eklediğinizden emin olun.
   → Adım adım kılavuz burada mevcuttur.

2. CGO'yu etkinleştirin ve uygulamayı çalıştırın

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go
   

Bu kurulum olmadan, muhtemelen şu gibi hatalarla karşılaşacaksınız:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Mimari Genel Bakış

Bu uygulama iki ana bileşenden oluşur:

1. Go WhatsApp Köprüsü (whatsapp-bridge/): WhatsApp'ın web API'sine bağlanan, QR kodu aracılığıyla kimlik doğrulamayı işleyen ve mesaj geçmişini SQLite'de depolayan bir Go uygulaması. WhatsApp ve MCP sunucusu arasında köprü görevi görür.

2. Python MCP Sunucusu (whatsapp-mcp-server/): Claude'un WhatsApp verileriyle etkileşim kurmasını ve mesaj göndermesini/almasını sağlayan standardlaştırılmış araçlar sağlayan Model Context Protocol (MCP) uygulayan bir Python sunucusu.

Veri Depolama

• Tüm mesaj geçmişi whatsapp-bridge/store/ dizinindeki bir SQLite veritabanında saklanır
• Veritabanı sohbetler ve mesajlar için tablolar içerir
• Mesajlar verimli arama ve alma için indekslenir

Kullanım

Bağlandıktan sonra, Claude aracılığıyla WhatsApp kişilerinizle etkileşim kurabilir ve Claude'un AI yeteneklerini WhatsApp sohbetlerinizde kullanabilirsiniz.

MCP Araçları

Claude, WhatsApp ile etkileşim kurmak için aşağıdaki araçlara erişebilir:

• search_contacts: Kişileri ada veya telefon numarasına göre arayın
• list_messages: İsteğe bağlı filtreler ve bağlam ile mesajları alın
• list_chats: Kullanılabilir sohbetleri meta verilerle listeleyin
• get_chat: Belirli bir sohbet hakkında bilgi alın
• get_direct_chat_by_contact: Belirli bir kişi ile doğrudan sohbeti bulun
• get_contact_chats: Belirli bir kişiyi içeren tüm sohbetleri listeleyin
• get_last_interaction: Bir kişi ile en son mesajı alın
• get_message_context: Belirli bir mesaj etrafındaki bağlamı alın
• send_message: Belirtilen bir telefon numarasına veya grup JID'sine WhatsApp mesajı gönderin
• send_file: Belirtilen bir alıcıya dosya (resim, video, ham ses, belge) gönderin
• send_audio_message: Ses dosyasını WhatsApp ses mesajı olarak gönderin (dosyanın .ogg opus dosyası olması veya ffmpeg'in yüklü olması gerekir)
• download_media: WhatsApp mesajından medya indirin ve yerel dosya yolunu alın

Medya İşleme Özellikleri

MCP sunucusu çeşitli medya türlerinin hem gönderilmesini hem de alınmasını destekler:

Medya Gönderme

Çeşitli medya türlerini WhatsApp kişilerinize gönderebilirsiniz:

• Resimler, Videolar, Belgeler: Desteklenen herhangi bir medya türünü paylaşmak için send_file aracını kullanın.
• Ses Mesajları: Ses dosyalarını çalınabilir WhatsApp ses mesajları olarak göndermek için send_audio_message aracını kullanın.
  • En uygun uyumluluk için, ses dosyaları .ogg Opus formatında olmalıdır.
  • FFmpeg yüklü olduğunda, sistem diğer ses formatlarını (MP3, WAV vb.) otomatik olarak gerekli formata dönüştürecektir.
  • FFmpeg olmadan, send_file aracını kullanarak ham ses dosyalarını yine de gönderebilirsiniz, ancak çalınabilir ses mesajları olarak görünmeyeceklerdir.

Medya İndirme

Varsayılan olarak, medyanın yalnızca metadata'sı yerel veritabanında saklanır. İleti medyanın gönderildiğini gösterecektir. Bu medyaya erişmek için, message_id ve chat_jid alan download_media aracını kullanmanız gerekir (bunlar medya içeren mesajları yazdırırken gösterilir), bu medyayı indirir ve ardından açılabilir veya başka bir araca gönderilebilecek dosya yolunu döndürür.

Teknik Detaylar

1. Claude, Python MCP sunucusuna istekler gönderir
2. MCP sunucusu, Go köprüsünü WhatsApp verileri için sorgular veya doğrudan SQLite veritabanına sorgular
3. Go, WhatsApp API'sine erişir ve SQLite veritabanını güncel tutar
4. Veriler zincirin geriye doğru Claude'a akar
5. Mesaj gönderirken, istek Claude'tan MCP sunucusu aracılığıyla Go köprüsüne ve WhatsApp'e akar

Sorun Giderme

• UV çalıştırırken izin sorunları yaşarsanız, bunu PATH'inize eklemeniz veya yürütülebilir dosyasının tam yolunu kullanmanız gerekebilir.
• Entegrasyonun düzgün çalışması için hem Go uygulaması hem de Python sunucusu çalışıyor olmalıdır.

Kimlik Doğrulama Sorunları

• QR Kodu Görüntülenmiyor: QR kodu görünmüyorsa, kimlik doğrulama betiğini yeniden başlatmayı deneyin. Sorunlar devam ederse, terminalinizin QR kodları görüntülemeyi destekleyip desteklemediğini kontrol edin.
• WhatsApp Zaten Oturum Açılmış: Oturumunuz zaten aktifse, Go köprüsü bir QR kodu göstermeden otomatik olarak yeniden bağlanacaktır.
• Cihaz Sınırına Ulaşıldı: WhatsApp bağlantılı cihazların sayısını sınırlandırır. Bu sınıra ulaşırsanız, telefonunuzdaki WhatsApp'tan mevcut bir cihazı kaldırmanız gerekir (Ayarlar > Bağlantılı Cihazlar).
• Mesaj Yüklenmediği: İlk kimlik doğrulamadan sonra, özellikle çok sayıda sohbetiniz varsa, mesaj geçmişinin yüklenmesi birkaç dakika sürebilir.
• WhatsApp Senkronize Olmadı: WhatsApp mesajlarınız köprü ile senkronize olmadıysa, her iki veritabanı dosyasını da silin (whatsapp-bridge/store/messages.db ve whatsapp-bridge/store/whatsapp.db) ve köprüyü yeniden kimlik doğrulamak için yeniden başlatın.

Claude Desktop entegrasyonu ile ilgili ek sorun giderme için MCP belgelerine bakın. Belgeler günlükleri kontrol etme ve yaygın sorunları çözme konusunda yararlı ipuçları içerir.