> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Sunucusu

> Yapay zekâ ajanlarının GOWA'nın /mcp adresindeki yerleşik Model Context Protocol uç noktası üzerinden WhatsApp'ı kullanmasını sağlayın.

GOWA, REST API ile aynı süreçten bir [Model Context Protocol](https://modelcontextprotocol.io) uç noktası sunar. **Akış destekli HTTP** aktarımını destekleyen herhangi bir MCP istemcisi bunun üzerinden mesaj gönderebilir, sohbetleri okuyabilir ve grupları yönetebilir.

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (varsayılan `http://localhost:3000/mcp`)
* Varsayılan olarak etkindir. `MCP_ENABLED=false` veya `--mcp-enabled=false` ile devre dışı bırakın.
* Durum bilgisi tutmaz: çağrılar arasında canlı tutulması gereken bir oturum el sıkışması yoktur.

> [!NOTE]
>
> Eski bir sürümden mi yükseltiyorsunuz? Bağımsız `./whatsapp mcp` komutu ve 8080 portundaki SSE uç noktası (`/sse`) kaldırılmıştır. `./whatsapp rest` çalıştırın ve istemcileri `/mcp` adresine yönlendirin. Eski, her işlem için ayrı araç içeren kümenin yerini aşağıdaki birleştirilmiş araçlar almıştır.

## İstemci bağlama

`/mcp`, REST API ile aynı Basic Auth korumasının arkasındadır. `Authorization` başlığını ve birden fazla cihaz çalıştırıyorsanız `X-Device-Id` başlığını gönderin:

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=`, `base64("admin:changeme")` değeridir; kendi değerinizi `echo -n 'user:pass' | base64` ile oluşturun. Basic Auth kapalıysa `Authorization` başlığını, yalnızca bir cihaz varsa `X-Device-Id` başlığını eklemeyin.

Yapılandırmanın tam biçimi istemciye bağlıdır. Bir istemci yalnızca stdio sunucularını başlatabiliyorsa `mcp-remote` gibi bir köprü kullanın.

## Araçlar

GOWA yedi araç sunar. Her biri işlemi seçen bir `type` (gönderim) veya `action` (diğer tümü) bağımsız değişkeni alır.

| Araç | `type` / `action` değerleri |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`, `get`, `pause`, `resume`, `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`, `list_contacts`, `get_messages`, `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

Bağımsız değişkenlere ilişkin notlar:

* `whatsapp_send` her zaman `type` ve `phone` gerektirir. Medya **yalnızca URL ile** gönderilir (`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP yerel dosya yükleyemez. `link`, `link` ve `caption` gerektirir; `forward`, `message_id` gerektirir.
* `whatsapp_send`, [zamanlama alanlarını](https://gowa-docs.mintlify.site/tr/examples/scheduled-sends.md) kabul eder (`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`). Sonucu `whatsapp_schedule` ile yönetin (`get`, `pause`, `resume` ve `cancel`, `schedule_id` gerektirir).
* `whatsapp_message`, `phone` (sohbet) ve `message_id` gerektirir; `edit` ayrıca `message` gerektirir.
* v9.9.0 sonrasındaki GOWA `main` sürümlerinde, `whatsapp_message`, `action: "edit"` ile kullanıldığında, açıklamayı değiştirmek için `media_type: "image"` veya `media_type: "document"` kabul eder. Özgün medya türüyle eşleştirin ve `link` eklemeyin. Bkz. [Açıklama düzenleme](https://gowa-docs.mintlify.site/tr/examples/sending-messages.md#g%C3%B6r%C3%BCnt%C3%BC-veya-belge-a%C3%A7%C4%B1klamas%C4%B1n%C4%B1-d%C3%BCzenleme).
* `whatsapp_chat`: `get_messages`, `chat_jid` gerektirir; `archive`, `chat_jid` ve `archived` gerektirir.
* `whatsapp_app`: `login_code`, `phone` gerektirir.

Deneysel düğme, konum isteği ve karusel gönderimleri yalnızca REST üzerinden kullanılabilir. Bkz. [Etkileşimli mesajlar](https://gowa-docs.mintlify.site/tr/examples/interactive-messages.md). Bülten araçları kanal keşfini, geçmiş sayaçlarını ve otomatik yenilenen canlı güncelleme aboneliklerini destekler. Bkz. [Bültenler](https://gowa-docs.mintlify.site/tr/examples/newsletters.md).

Medya URL'sinden indirmeler, REST gönderimleriyle aynı genel adres kontrollerini uygular ve `HTTP_PROXY` veya `HTTPS_PROXY` kullanmadan doğrudan bağlanır. Yerel dosyalardan yükleme için REST API gerekir.

MCP istemciniz her aracın tam girdi şemasını gösterir. HTTP uç noktası POST ve DELETE kabul eder. GET SSE akışı devre dışıdır.

## Cihaz seçimi

Her çağrı cihazını şu sırayla belirler:

1. Araç çağrısındaki `device_id` bağımsız değişkeni.
2. MCP bağlantısındaki `X-Device-Id` başlığı.
3. Tam olarak bir cihaz varsa kayıtlı tek cihaz.

Aksi halde çağrı `device identification required: set the X-Device-Id header or pass device_id` hatasıyla başarısız olur. Bkz. [Çoklu cihaz](https://gowa-docs.mintlify.site/tr/concepts/multidevice.md).

## OAuth kullanan uzak istemciler

Claude özel bağlayıcıları gibi barındırılan istemciler Basic Auth başlığı ekleyemez. GOWA, bunlar için `/mcp` üzerinde bir OAuth 2.1 yetkilendirme sunucusu çalıştırabilir. Varsayılan olarak kapalıdır.

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

Gereksinimler ve davranış:

* `APP_BASIC_AUTH` ayarlanmalıdır: yetkilendirme sayfası kullanıcıların aynı hesaplarla giriş yapmasını sağlar. Bu olmadan başlangıç başarısız olur.
* Yayıncı ve kaynak, `http://gowa:3000` gibi dahili adresler değil, istemcilerin gördüğü **genel HTTPS** URL'leri olmalıdır.
* OAuth açıkken `/mcp`, Bearer belirteci **veya** Basic Auth kabul eder. Belirteçler REST veya arayüz yollarında kabul edilmez.
* İstemciler kendilerini kaydeder (RFC 7591 dinamik istemci kaydı). Kayıt gövdeleri 16 KiB, her yönlendirme URI'si 2 KiB ile sınırlıdır. Kayıtlar saatte 40 ve saklanan istemciler 1.000 ile sınırlıdır; kullanılmayanlar 24 saat sonra temizlenir.
* PKCE `S256` zorunludur. Kodların süresi 5 dakika, erişim belirteçlerinin süresi 1 saat sonra dolar; yenileme belirteçleri döndürülür ve eski bir belirteci yeniden kullanmak tüm belirteç ailesini iptal eder. Yalnızca belirteçlerin SHA-256 karmaları `MCP_OAUTH_DB_URI` içinde saklanır (varsayılan `file:storages/oauth.db`).

Yönlendirme URI'leri kayıtlı değerlerle tam olarak eşleşmelidir. Yerel istemciler dinamik portlu HTTP loopback IP geri çağrılarını kullanabilir. `localhost` geri çağrıları açıkça belirtilmiş bir port ve tam eşleşme gerektirir. Diğer yönlendirmeler HTTPS gerektirir. OAuth `resource`, standart MCP URL'sine bağlıdır; belirteç istekleri bunu atlayabilir ancak sağlanan değer eşleşmelidir. Başarılı yetkilendirme yanıtları `iss` içerir.

Süresi dolan kodlar ve belirteçler OAuth yazma işlemlerinde temizlenir. Döndürülmüş yenileme belirteci karmaları, etkin bir aileye karşı yeniden kullanımı tespit etmek için gerektiği sürece, en fazla 30 günlük bir ek yenileme belirteci ömrü boyunca tutulur. OAuth veritabanını silmek veya değiştirmek mevcut istemcileri ve yetkileri geçersiz kılar.

Yayıncıya göre uç noktalar: `/oauth/authorize`, `/oauth/token`, `/oauth/register`. Keşif meta verileri, etki alanı kökünde yol eklemeli well-known URL'lerini kullanır; dolayısıyla `APP_BASE_PATH=/gowa` ile vekiliniz şu adresleri yönlendirmelidir:

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

Keşfi dışarıdan kontrol edin:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

Ardından `https://gowa.example.com/mcp` adresini özel bağlayıcı olarak ekleyin ve bir `APP_BASIC_AUTH` hesabıyla giriş yapın.

> [!WARNING]
>
> GOWA'nın önündeki Cloudflare Access, bot kontrolleri veya kimlik doğrulama vekillerinin well-known, `/oauth/*` veya `/mcp` yollarına müdahale etmediğinden emin olun. Vekilinizde `/oauth/authorize` üzerindeki başarısız girişlere hız sınırı uygulayın.


## Related topics

- [API Referansı](https://gowa-docs.mintlify.site/tr/api-reference/introduction.md)
- [Zamanlanmış Gönderimler](https://gowa-docs.mintlify.site/tr/examples/scheduled-sends.md)
- [API Kimlik Doğrulaması](https://gowa-docs.mintlify.site/tr/api-reference/authentication.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/tr/index.md)
- [Çoklu Cihaz ve Cihaz Seçimi](https://gowa-docs.mintlify.site/tr/concepts/multidevice.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.