notify-mcp

Claude Code için masaüstü ve e-posta bildirimi sağlayan, yerel olarak çalışan bir Model Context Protocol (MCP) sunucusu.

notify-mcp, Claude Code uzun süren bir görevi tamamladığında kullanıcıyı bilgilendirmek için iki kanal sunar: işletim sisteminin yerel bildirim altyapısı ve Gmail SMTP üzerinden gönderilen e-posta. Bildirimler Claude tarafından MCP araçları aracılığıyla istenerek ya da isteğe bağlı bir Stop hook'u ile her yanıtın sonunda otomatik olarak gönderilebilir.

Özellikler

• Masaüstü bildirimi: Windows, macOS ve Linux'ta yerel, sesli sistem bildirimi.

• E-posta bildirimi: Yapılandırılan Gmail hesabından aynı adrese düz metin e-posta.

• Otomatik tamamlanma bildirimi: Claude her yanıtını bitirdiğinde sesli uyarı ve son yanıtın özetini içeren e-posta gönderen Stop hook'u.

• Kullanıcı tercihlerine duyarlılık: Hook, kullanıcının mesajlarını analiz eder. Bir kanalın istenmediği belirtilirse (ör. "e-posta gönderme") o kanalı tek tur ya da sohbet boyunca atlar.

• Tekrarlanan bildirimlerin önlenmesi: Claude aynı turda bildirimi MCP aracıyla zaten gönderdiyse hook ikinci kez göndermez.

Related MCP server: Email MCP Server

İçindekiler

• Mimari

• Gereksinimler

• Kurulum

• Yapılandırma

• Claude Code entegrasyonu

• Bildirim tercihleri

• MCP araç referansı

• Proje yapısı

• Geliştirme

• Güvenlik

• Sorun giderme

• Lisans

Mimari

flowchart LR
    CC["Claude Code"] -- "stdio (JSON-RPC)" --> SRV["MCP sunucusu<br/>index.js"]
    SRV --> DESK["Masaüstü bildirimi<br/>node-notifier"]
    SRV --> MAIL["mailer.js"]
    CC -- "Stop hook" --> HOOK["stop-notify.js"]
    HOOK --> INTENT["prompt-intent.js<br/>tercih analizi"]
    HOOK --> BEEP["Sesli uyarı"]
    HOOK --> MAIL
    MAIL --> SMTP["Gmail SMTP<br/>port 465 / SSL"]

Gereksinimler

Kurulum

git clone https://github.com/Harley-Quinnz/notify-mcp.git
cd notify-mcp
npm install

Yapılandırma

E-posta bildirimi için şablon dosyayı kopyalayın ve kendi bilgilerinizle doldurun:

# macOS / Linux / Git Bash
cp .env.example .env

# Windows (CMD / PowerShell)
copy .env.example .env

EMAIL_USER=ornek@gmail.com
EMAIL_PASS=xxxx xxxx xxxx xxxx

.env dosyası her gönderimde yeniden okunduğundan, değerler değiştirildiğinde sunucuyu yeniden başlatmak gerekmez.

Gmail uygulama şifresi oluşturma

1. Google hesabınızda 2 Adımlı Doğrulama'yı etkinleştirin.

2. https://myaccount.google.com/apppasswords adresine gidin.

3. Yeni bir uygulama şifresi oluşturun ve 16 karakterlik değeri EMAIL_PASS olarak kaydedin.

Claude Code entegrasyonu

MCP sunucusu

Sunucuyu tüm projelerde kullanılabilir olacak şekilde (user scope) ekleyin. Dosya yolunu deponun bulunduğu konuma göre düzenleyin:

# Windows
claude mcp add --scope user notify -- node "C:\\Users\\<kullanici>\\notify-mcp\\index.js"

# macOS / Linux
claude mcp add --scope user notify -- node /home/<kullanici>/notify-mcp/index.js

Alternatif olarak yapılandırma dosyasına elle ekleyebilirsiniz:

{
  "mcpServers": {
    "notify": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\<kullanici>\\notify-mcp\\index.js"]
    }
  }
}

Kurulumu doğrulamak için Claude Code içinde /mcp komutunu çalıştırın. notify sunucusu connected durumunda görünmelidir. Ardından Claude'dan doğrudan bildirim isteyebilirsiniz:

Testleri çalıştır, tamamlandığında masaüstü bildirimi ve e-posta gönder.

Stop hook (isteğe bağlı)

stop-notify.js, Claude her yanıtını tamamladığında çalışır:

• Kısa bir sesli uyarı çalar (Windows: [Console]::Beep, macOS: afplay).

• Proje klasörü, zaman, oturum kimliği ve son yanıtın özetini (en fazla 4000 karakter) içeren bir e-posta gönderir.

Hook'u etkinleştirmek için ~/.claude/settings.json dosyasına ekleyin:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["C:\\Users\\<kullanici>\\notify-mcp\\stop-notify.js"],
            "async": true,
            "timeout": 60
          }
        ]
      }
    ]
  }
}

async: true ayarı bildirimlerin Claude'u bekletmemesini sağlar. Hatalar ve atlanan bildirimler proje klasöründeki stop-notify.log dosyasına kaydedilir.

Bildirim tercihleri

Stop hook, sohbetteki kullanıcı mesajlarını analiz ederek her kanal için gönderim kararı verir. Tercihler iki kapsamda uygulanır.

Tek tur

Mesajda bir kanalın istenmediği ya da yalnızca birinin istendiği belirtilirse karar yalnızca o tur için geçerlidir. Sonraki mesajda varsayılan davranışa dönülür.

Sohbet boyunca

Mesajda "bu sohbet boyunca", "ben söyleyene kadar", "aksini söyleyene kadar", "bundan sonra" veya "artık" gibi bir ifade bulunursa ya da "kapat" / "aç" fiilleri kullanılırsa tercih, değiştirilene kadar sohbetin geri kalanında geçerli olur.

Davranış ayrıntıları

• Sohbet kapsamındaki tercihler yalnızca ilgili sohbet için geçerlidir. Karar her seferinde sohbetin transcript'inden hesaplanır. Yeni bir sohbet ya da /clear sonrası varsayılan davranış geçerlidir.

• Sohbet boyunca kapatılmış bir kanal, bir turda açıkça istenirse ("bitince mail at") o tur için gönderilir.

• Aynı mesajda bir kanal hem istenip hem reddedilirse kanal kapalı kabul edilir.

• Türkçe karakter kullanımı ("gonderme", "eposta") ve büyük/küçük harf farkı sonucu etkilemez. İngilizce ifadeler de desteklenir.

• İsim olarak kullanılan ifadeler ("e-posta gönderme özelliğini düzelt") ve kod blokları içindeki metinler komut olarak değerlendirilmez.

• Ayrıştırıcı kural tabanlıdır. Desteklenmeyen bir ifade fark edilmezse varsayılan davranış (gönderim) uygulanır.

MCP araç referansı

send_desktop_notification

Yerel, sesli bir masaüstü bildirimi gösterir.

send_email_notification

EMAIL_USER adresine, aynı adresten düz metin e-posta gönderir (Gmail SMTP, port 465, SSL).

Proje yapısı

notify-mcp/
├── index.js           MCP sunucusu ve araç tanımları
├── mailer.js          Gmail SMTP üzerinden e-posta gönderimi
├── stop-notify.js     Claude Code Stop hook'u
├── prompt-intent.js   Bildirim tercihlerinin ayrıştırılması
├── .env.example       Ortam değişkenleri şablonu
├── package.json
├── LICENSE
└── README.md

Geliştirme

Hook kararlarını test etme

NOTIFY_DRY_RUN=1 ortam değişkeni ile hook hiçbir bildirim göndermeden verdiği kararı JSON olarak yazdırır:

echo '{"transcript_path":"<transcript.jsonl>"}' | NOTIFY_DRY_RUN=1 node stop-notify.js

stdout kullanımı

stdio transport, stdout akışını JSON-RPC iletişimi için kullanır. Sunucu kodunda console.log kullanılmamalı, tüm loglar console.error (stderr) ile yazılmalıdır.

Güvenlik

• .env dosyası .gitignore ile depo dışında tutulur. Depoda yalnızca değer içermeyen .env.example bulunur.

• Gmail hesap şifresi yerine her zaman uygulama şifresi kullanın. Uygulama şifreleri hesap şifresini değiştirmeden tek tek iptal edilebilir.

• Uygulama şifresinin sızdığından şüpheleniyorsanız https://myaccount.google.com/apppasswords üzerinden iptal edip yenisini oluşturun.

• Sunucu yerel olarak çalışır ve Gmail SMTP dışında herhangi bir dış servise veri göndermez.

Sorun giderme

Lisans

Bu proje MIT lisansı ile lisanslanmıştır. Ayrıntılar için LICENSE dosyasına bakın.