WhatsApp MCP eğitimlerinin çoğu Claude Desktop'ta durur. Bu Whapi.Cloud kılavuzu Cursor, VS Code ve GitHub Copilot kullanan geliştiriciler için yazılmıştır — her biri için kopyala-yapıştır JSON yapılandırmaları ve çalışan bir doğrulama adımıyla.
WhatsApp otomasyonu bir zamanlar özel kod gerektiriyordu — REST istemcileri, webhook işleyicileri, oturum yönetimi ve token yenileme mantığı. whapi-mcp tüm bunları AI ajanınıza yönelik doğal dil komutlarıyla değiştirir. MCP sunucusunu bir kez kurun, bir JSON yapılandırması yapıştırın ve tam WhatsApp araç kütüphanesi halihazırda kullandığınız MCP uyumlu herhangi bir istemciye açık olsun.
MCP Gerçekte Nedir
MCP — Model Context Protocol — AI ajanlarının gerçek harici araçları çağırması için bir eklenti sistemidir. Tek arayüz, pek çok uyumlu istemci: bir MCP sunucusu çalıştırın ve her bağlı ajan, istemci başına ayrı entegrasyonlar olmaksızın araçlarını kullanabilir.
MCP olmadan ajanınız yalnızca eylemler önerebilir. MCP ile onları gerçekleştirir — bir API çağırır, bir mesaj dizisini okur, yanıt gönderir, teslimi onaylar. Öneri ile otomasyon arasındaki fark, araç erişimidir.
whapi-mcp Size Ne Kazandırır
whapi-mcp, Whapi.Cloud tarafından geliştirilmiş, Whapi REST API'sini sarmalayan ve herhangi bir MCP uyumlu AI ajanına yapılandırılmış araçlar olarak sunan bir MCP sunucusudur. Whapi OpenAPI spesifikasyonundan otomatik olarak oluşturulan araçlar; mesajlar, gruplar, kanallar, kişiler, medya, etiketler ve daha fazlasını kapsar — toplamda 165 araç.
Cursor, VS Code Agent Mode, GitHub Copilot Chat, Windsurf ve Claude Desktop'ta çalışır. Beş istemcinin tamamı aynı npm paketini kullanır: @whapi-cloud/whapi-mcp. Aralarındaki tek fark yapılandırma dosyası yoludur.
QR tabanlı köprülerin aksine whapi-mcp, Whapi'nin üretim altyapısı üzerinden bağlanır — yerel oturum dosyası yok, ağ kesintilerinden sonra yeniden tarama yok, gece yarısı yeniden bağlantı yok. Kararlılık bulutta yönetilir, geliştirici makinenizde değil.
| Özellik | whapi-mcp (Whapi.Cloud) | QR Köprüsü (yerel oturum) |
|---|---|---|
| Oturum kararlılığı | Üretim kararlılığı, bulut yönetimli | Ağ kesintisinde düşer; QR yeniden tarama gerektirir |
| Kurulum süresi | 10 dakikadan az (tek npx komutu) | 30 -- 60 dk (yerel sunucu + QR tarama + port yapılandırması) |
| Çoklu numara desteği | Evet — hesap başına birden fazla kanal | Genellikle sunucu örneği başına bir numara |
| MCP araç kapsamı | OpenAPI spesifikasyonundan 165 yapılandırılmış araç | Değişken; çoğunlukla özel sarmalayıcı gerektirir |
| Gruplar ve Kanallar API'si | Tam erişim | Kısmi veya güvenilmez |
Başlamadan Önce
Herhangi bir kurulum komutu çalıştırmadan önce şu önkoşulları kontrol edin:
-
Node.js 18 veya üzeri —
npxçalıştırmak için gereklidir. Terminalinizdenode -vile doğrulayın. -
Whapi API token'ı — whapi.cloud'a kaydolun, bir WhatsApp numarası bağlayın ve token'ı Whapi kontrol panelindeki kanal ayarlarından kopyalayın.
-
MCP uyumlu IDE — Cursor (herhangi bir güncel sürüm), Agent Mode etkinleştirilmiş VS Code veya uygun Copilot planıyla VS Code 1.99+'da GitHub Copilot Chat.
WhatsApp MCP'yi 10 Dakikada Bağlayın
Cursor, VS Code ve GitHub Copilot aynı @whapi-cloud/whapi-mcp paketini kullanır — yalnızca yapılandırma dosyası yolu farklıdır. Paketi npx aracılığıyla bir kez kurun; IDE başına bir kez yapılandırın.
Adım 1 — Doğrulamak için Sunucuyu Bir Kez Çalıştırın
Herhangi bir IDE yapılandırmadan önce, paketin çözümlendiğini ve token'ın geçerli olduğunu onaylamak için bunu terminalinizde çalıştırın:
npx -y @whapi-cloud/whapi-mcp --api-token YOUR_WHAPI_TOKENYOUR_WHAPI_TOKEN'ı gerçek token'ınızla değiştirin. MCP sunucusu hatasız başlarsa — token çalışıyor demektir. Global npm kurulumu gerekmez; IDE yapılandırması başlangıçta npx'i otomatik olarak çalıştırır.
Adım 2 — IDE'nizi Yapılandırın
Her IDE, MCP sunucu yapılandırmasını belirli bir JSON dosyasından okur. İç yapı üç istemcide de neredeyse aynıdır — yalnızca dış anahtar ve dosya konumu farklıdır.
Cursor
Global yapılandırma için ~/.cursor/mcp.json dosyasını oluşturun veya düzenleyin (tüm projelere uygulanır) ya da proje kapsamlı yapılandırma için proje kökünüzde .cursor/mcp.json oluşturun:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Kaydedin, Cursor'ı yeniden başlatın ve ajan panelini açın — whapi araçları mevcut araç listesinde görünür.
VS Code (Agent Mode)
Workspace kökünüzde .vscode/mcp.json oluşturun. VS Code Agent Mode bu dosyayı otomatik olarak okur. VS Code'un MCP yapılandırma şemasının gerektirdiği "type": "stdio" anahtarına dikkat edin:
{
"servers": {
"whapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Henüz etkin değilse VS Code ayarlarından Agent Mode'u etkinleştirin. whapi sunucusu ajan panelini açtığınızda başlayacaktır.
GitHub Copilot (VS Code)
VS Code'da GitHub Copilot Chat için, kullanıcı düzeyindeki settings.json dosyanıza MCP girdisini ekleyin ya da proje kökünde .github/copilot/mcp.json oluşturun. MCP desteği VS Code 1.99+ ve uygun bir Copilot planı gerektirir:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Kaydettikten sonra Agent modunda Copilot Chat'i açın — whapi araçları araç seçicisinde görünür.
Claude Desktop
Claude Desktop da kullanıyorsanız yapılandırma claude_desktop_config.json dosyasına gider. Yapı Cursor yapılandırmasıyla aynıdır:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Adım 3 — Token'ınızı Güvence Altına Alın
Whapi API token'ını sürüm kontrolüne gönderdiğiniz bir yapılandırma dosyasına yapıştırmayın. Bunun yerine bir ortam değişkenine başvurun — çoğu MCP istemcisi sunucu yapılandırmasında "env" anahtarını destekler:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "${WHAPI_TOKEN}"]
}
}
}WHAPI_TOKEN'ı sistem ortamınızda veya git dışında tutulan bir .env dosyasında tanımlayın. Ham token içeriyorsa yapılandırma dosyasını .gitignore'a ekleyin. Tam örnekler Whapi MCP kurulum kılavuzunda bulunabilir.
Bağlantınızı Doğrulayın
IDE'yi yeniden başlattıktan sonra AI ajanınızı açın ve şunu çalıştırın:
List my WhatsApp chatsÇalışan bir bağlantı, son sohbetlerinizi Chat ID'leriyle birlikte döndürür. Görünürlerse — kurulum tamamlanmıştır. AI ajanınızın artık doğrudan WhatsApp erişimi var.
MCP sunucu hataları neredeyse her zaman iki hataya bağlıdır: yanlış yapılandırma dosyası yolu veya JSON'daki sondaki virgüller. Her ikisi de sessiz parse hatalarına yol açar.
Neler Yapabilirsiniz — 6 Gerçek Kullanım Senaryosu
MCP'yi bir kez bağlayın; AI ajanınız düz dil komutlarıyla mesaj gönderir, grupları yönetir ve sohbetleri okur. Kurulumdan sonra hemen çalışan altı işlem:
-
"Ahmet'e siparişinin hazır olduğunu söyleyen bir mesaj gönder" — ajan Ahmet'in Chat ID'si ve mesaj gövdesiyle
sendMessageText'i çağırır. -
"Sprint Team adında bir WhatsApp grubu oluştur ve şu 5 numarayı ekle" — grubu oluşturmak için
createGroup'u, ardından katılımcı dizisiyleaddGroupParticipant'ı çağırır. -
"Destek sohbetinden son 20 mesajı oku" — sohbet ID'si ve sayısıyla
getMessages'i çağırır. Tüm diziyi döndürür. -
"invoice.pdf'yi müşteriye WhatsApp'tan gönder" — dosya referansı ve alıcı Chat ID'siyle
sendMessageDocument'i çağırır. -
"Tüm okunmamış sohbetleri listele ve konularını özetle" — sohbet listesi için
getChats'i, ardından sohbet başınagetMessages'i çağırır — AI bağlamı çıkarır ve özetler. -
"WhatsApp kanalımıza bir ürün güncellemesi yayınla" — alıcı olarak kanalın
CHANNELID@newsletterChat ID'siylesendMessageText'i çağırır.
Her komut tek bir araç çağrısına karşılık gelir. Ajan aracı seçer, parametreleri doldurur ve sonucu döndürür — yazılacak veya bakımı yapılacak entegrasyon kodu yoktur.
Whapi Agent Skill — Format Hatalarını Ortadan Kaldırın
AI ajanları WhatsApp Chat ID'lerini halüsine eder. Açık format bilgisi olmadan model yapısal olarak yanlış tanımlayıcılar icat eder — ve ajan doğru aracı seçse bile araç çağrısı başarısız olur.
WhatsApp, tam olarak kullanılması gereken üç farklı Chat ID formatı kullanır:
-
[email protected]— bireysel kişiler (örn.[email protected]) -
[email protected]— grup sohbetleri (örn.[email protected]) -
CHANNELID@newsletter— WhatsApp Kanalları (örn.120363123456789012@newsletter)
Whapi Agent Skill, Cursor ve VS Code için indirilebilir bir bilgi dosyasıdır. Bir kez kurun — ajan her oturum öncesinde Chat ID format kurallarını ve kullanım kalıplarını bağlamına yükler. İlk denemede başarı oranı artar; Chat ID hata ayıklaması neredeyse sıfıra iner.
Kurulum talimatları Whapi Agent Skills kılavuzunda bulunabilir. whapi-mcp ve Agent Skill'i birlikte kullanın — bunlar bunun için tasarlandı.
Hızlı Sorun Giderme
Başarısız kurulumların çoğuna yol açan üç sorun:
-
IDE yeniden başlatıldıktan sonra MCP sunucusu bulunamadı — yapılandırma dosyası yanlış yolda ya da JSON söz dizimi hatası var. Cursor global yapılandırması
~/.cursor/mcp.jsonkonumundadır. VS Code,.vscode/mcp.json'ı workspace kökünden okur. JSON'ınızı bir linter ile doğrulayın — sondaki virgüller sessiz parse hatalarına neden olur. -
Kimlik doğrulama hatası veya 401 yanıtı — API token'ı geçersiz, süresi dolmuş ya da fazladan boşlukla yapıştırılmış. Doğrudan Whapi kontrol panelindeki kanal ayarlarından yeniden kopyalayın ve yapılandırmadaki değeri değiştirin.
-
npx paketi çözümleyemiyor — Node.js 18+'ın kurulu olduğunu doğrulayın (
node -v). Kurumsal ağlarda veya VPN'de npm registry erişiminin engellenmediğini kontrol edin. Yedek olaraknpm install -g @whapi-cloud/whapi-mcp'yi deneyin ve yapılandırmayı"command": "whapi-mcp"kullanacak şekilde güncelleyin.
Uç durumlar ve ek yapılandırma kalıpları için Whapi MCP kurulum kılavuzuna bakın. Kaynak kod ve açık issue'lar GitHub'da (Whapi-Cloud/whapi-mcp) bulunabilir.
API token'ınızı alın ve ilk WhatsApp ajan komutunuzu 10 dakikadan kısa sürede çalıştırın. Burada ele alınmayan bir uç durumla karşılaşırsanız bu sayfadaki destek sohbetini açın — Whapi ekibi hızlı yanıt verir.
