Mac Messages MCP

macOS Messages uygulamasıyla etkileşim kurmak için MCP (Multiple Context Protocol) kullanan bir Python köprüsü.

Hızlı Yükleme

Cursor Kullanıcıları İçin

Mac Messages MCP'yi Cursor'a otomatik olarak eklemek için yukarıdaki düğmeye tıklayın

Claude Desktop Kullanıcıları İçin

Kurulum talimatları için aşağıda Integration bölümüne bakın.

Özellikler

• Evrensel Mesaj Gönderme: Alıcının durumuna göre otomatik olarak iMessage veya SMS/RCS üzerinden gönderir
• Akıllı Geri Dönüş: iMessage kullanılamadığında SMS'e sorunsuz geçiş (Android kullanıcıları için mükemmel)
• Mesaj Okuma: macOS Messages uygulamasından son mesajları okuyun
• Kişi Filtrelemesi: Mesajları belirli kişilere veya telefon numaralarına göre filtreleyin
• Grup Sohbeti Filtrelemesi: tool_get_chats'ten sohbet kimliklerini kullanarak bir grup konuşmasını kronolojik olarak okuyun
• Bulanık Arama: Mesaj içeriğinde akıllı eşleştirme ile arama yapın
• Ekler: Sohbetlerde paylaşılan fotoğraflar, PDF'ler ve diğer ekleri bulun ve görüntüleyin
• iMessage Algılama: Gönderilmeden önce alıcıların iMessage'a sahip olup olmadığını kontrol edin
• Platformlar Arası: iPhone/Mac kullanıcıları (iMessage) ve Android kullanıcıları (SMS/RCS) ile çalışır

Eklerle çalışmak

Ek erişimi aşamalı açıklama kullanır — keşif ucuz, getirme ise kasıtlıdır:

1. Seviye 1 — ileti arama sırasında keşif. tool_get_recent_messages ve tool_fuzzy_search_messages, ekleri olan mesajları [attachments: #42 image/jpeg (invitation.jpg)] gibi kompakt bir özet ile açıklama yapar. Kimlik daha sonra dosyayı getirmek için kullanılabilir.
2. Seviye 2 — ek-öncelikli arama. tool_search_attachments(start_date, end_date, contact, mime_type, limit) yalnızca meta veriler (kimlik, MIME türü, dosya adı, boyut, gönderici) döndürür — "2026 yılının Nisan ayında Elizabeth'in gönderdiği tüm görselleri bul" gibi işlemler için ileti metnini taramadan faydalı.
3. Seviye 3 — getir. tool_get_attachment(attachment_id) dosyayı döndürür. Görüntü MIME türleri satır içine alınır (HEIC doğrudan görüntülenebilmesi için PNG'ye dönüştürülür). PDF'ler, video ve ses, aracının kendi araçları ile okuyabileceği bir dosya sistemi yolu olarak döndürülür. Satır içi görüntü baytları, bağlam şişkinliğini önlemek için varsayılan olarak 5MB ile sınırlandırılır; büyük görüntüler yol dönüşüne geri döner.

Stickers, bağlantı önizleme "balon" yükleri ve .pluginPayloadAttachment konteynerları varsayılan olarak filtrelenir.

Alıcı formatları

Doğrudan göndermeler için, E.164 telefon numaraları +14155551234 gibi önde gelen + ile en güvenilir formattır. Ülke kodu olan düz rakamlı telefon numaraları gönderilmeden önce normalleştirilir ve 10 haneli ABD numaraları +1... olarak gönderilir. tool_find_contact telefon eşleşmelerini aynı gönderme-hazır formatta döndürür.

Ön Koşullar

• macOS (macOS 11+ üzerinde test edildi)
• Python 3.10+
• uv paket yöneticisi

uv Yükleme

Mac'teyseniz, Homebrew kullanarak uv'yi yükleyin:

brew install uv

Aksi takdirde, uv web sitesindeki yükleme talimatlarını izleyin.

⚠️ uv yüklemeden devam etmeyin

Yükleme

Tam Disk Erişim İzni

⚠️ Bu uygulama, terminale veya uygulamaya Messages veritabanına erişmek için Tam Disk Erişim izni gerektirir.

Tam Disk Erişim vermek için:

1. Sistem Tercihleri/Ayarları > Güvenlik & Gizlilik/Gizlilik > Tam Disk Erişim'i açın
2. Değişiklik yapmak için kilit simgesine tıklayın
3. Terminal uygulamanızı (Terminal, iTerm2, vb.) veya Claude Desktop/Cursor'ı listeye ekleyin
4. İzin verdikten sonra terminali veya uygulamayı yeniden başlatın

Entegrasyon

Claude Desktop Entegrasyonu

Seçenek 1: Claude Desktop Uzantısı

Bu repo, Claude Desktop'ın tek tıkla uzantı akışı için MCPB uyumlu manifest.json içerir.

yarn global add @anthropic-ai/mcpb
mcpb pack

Oluşturulan .mcpb dosyasını Claude Desktop Ayarları > Uzantılar > Gelişmiş ayarlar > Uzantı Yükle...'den yükleyin.

Claude Desktop veya uzantıyı paketlemek/çalıştırmak için kullanılan terminal, Messages'ı okumak için hala Tam Disk Erişim'e ihtiyaç duyar.

Seçenek 2: Manuel Yapılandırma

1. Claude > Ayarlar > Geliştirici > Yapılandırma Düzenle > claude_desktop_config.json'a gidin
2. Aşağıdaki yapılandırmayı ekleyin:

{
    "mcpServers": {
        "messages": {
            "command": "uvx",
            "args": [
                "mac-messages-mcp"
            ]
        }
    }
}

Cursor Entegrasyonu

Seçenek 1: Tek Tıkla Yükleme (Önerilir)

Seçenek 2: Manuel Kurulum

Cursor Ayarları > MCP'ye gidin ve bunu komut olarak yapıştırın:

uvx mac-messages-mcp

⚠️ MCP sunucusunun yalnızca bir örneğini çalıştırın (Cursor veya Claude Desktop'ta), her ikisini de değil

Docker Konteyner Entegrasyonu

Docker konteynerinden mac-messages-mcp'ye bağlanmanız gerekiyorsa, stdio tabanlı sunucuyu HTTP'ye bağlamak için mcp-proxy paketini kullanmanız gerekir.

Bu repository ayrıca katalog kontrolleri ve konteyner derlemesi için bir Dockerfile içerir:

docker build -t mac-messages-mcp .

Messages.app otomasyonu yalnızca macOS özel olup, Linux konteyneri içinde çalışmaz. Konteyner kullanımı birincil olarak MCP katalog uyumluluğu ve takılı veriler ile salt okunur veritabanı deneyleri içindir.

Kurulum Talimatları

1. macOS ana makinenize mcp-proxy yükleyin:

npm install -g mcp-proxy

2. Proxy sunucusunu başlatın:

# Yayınlanan sürümü kullanarak
npx mcp-proxy uvx mac-messages-mcp --port 8000 --host 0.0.0.0

# Veya sorunlarla karşılaşırsanız yerel geliştirmeyi kullanarak
npx mcp-proxy uv run python -m mac_messages_mcp.server --port 8000 --host 0.0.0.0

3. Docker'dan bağlantı kurun: Docker konteyneriniz artık şu adreslere bağlanabilir:

• URL: http://host.docker.internal:8000/mcp (macOS/Windows'ta)
• URL: http://<host-ip>:8000/mcp (Linux'ta)

4. Docker Compose örneği:

version: '3.8'
services:
  your-app:
    image: your-image
    environment:
      MCP_MESSAGES_URL: "http://host.docker.internal:8000/mcp"
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux ana makineler için

5. Birden fazla MCP sunucusu çalıştırma:

# Terminal 1 - Messages MCP, port 8001'de
npx mcp-proxy uvx mac-messages-mcp --port 8001 --host 0.0.0.0

# Terminal 2 - Başka bir MCP sunucusu, port 8002'de
npx mcp-proxy uvx another-mcp-server --port 8002 --host 0.0.0.0

Not: 0.0.0.0'a bağlanmak, hizmeti tüm ağ arayüzlerine maruz bırakır. Üretimde, daha kısıtlayıcı ana bilgisayar bağlamalarını ve kimlik doğrulama eklemeyi göz önünde bulundurun.

Seçenek 1: PyPI'den Yükleme

uv pip install mac-messages-mcp

Seçenek 2: Kaynaktan Yükleme

# Deposu klonlayın
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# Bağımlılıkları yükleyin
uv install -e .

Kullanım

Akıllı Mesaj Teslimi

Mac Messages MCP, farklı platformlar arasında ileti teslimini otomatik olarak yönetir:

• iMessage Kullanıcıları (iPhone, iPad, Mac): iMessage üzerinden gönderilen mesajlar
• Android Kullanıcıları: Mesajlar otomatik olarak SMS/RCS'ye geri döner
• Karışık Gruplar: Her alıcı için optimal teslim yöntemi seçilir

# iPhone kullanıcısına gönder - iMessage kullanır
send_message("+1234567890", "Hey! This goes via iMessage")

# Android kullanıcısına gönder - otomatik olarak SMS kullanır
send_message("+1987654321", "Hey! This goes via SMS") 

# Gönderilmeden önce teslim yöntemini kontrol et
check_imessage_availability("+1234567890")  # Kullanılabilirlik durumunu döndürür

Modül Olarak

from mac_messages_mcp import get_recent_messages, send_message

# Son mesajları al
messages = get_recent_messages(hours=48)
print(messages)

# Mesaj gönder (iMessage veya SMS'i otomatik olarak seçer)
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)  # iMessage veya SMS aracılığıyla gönderilip gönderilmediğini gösterir

Komut Satırı Aracı Olarak

# MCP sunucusunu doğrudan çalıştır
mac-messages-mcp

Geliştirme

Sürüm Oluşturma

Bu proje anlamsal sürümü kullanır. Sürüm sisteminin nasıl çalıştığı ve yeni sürümleri nasıl yayınlayacağınız hakkında ayrıntılar için VERSIONING.md'ye bakın.

Sürümü güncellemek için:

python scripts/bump_version.py [patch|minor|major]

Güvenlik Notları

Bu uygulama, kişisel iletişimleri içeren Messages veritabanına doğrudan erişir. Lütfen bunu sorumlu bir şekilde kullanın ve uygun izinlere sahip olduğunuzdan emin olun.

Lisans

MIT

Katkıda Bulunma

Katkılar memnuniyetle karşılanır! Lütfen bir Pull Request göndermekten çekinmeyin.

Yıldız Tarihi