Claude, Cursor ve diğer MCP uyumlu istemciler için Telegram entegrasyonu. Telegram hesabı, sohbet, mesaj, iletişim, medya, klasör ve yönetici işlemlerini Model Context Protocol aracılığıyla Telethon kullanarak açığa çıkarır.

🤖 MCP Uygulamada

Claude'da temel Telegram MCP kullanımı:

Claude'tan sohbet geçmişini analiz etmesi ve yanıt göndermesi istenmesi:

Mesaj başarıyla gönderildi:

Neler Yapabilir

Sunucu şu alanlara ayrılmış 80+ MCP aracı içerir:

Hesaplar: yapılandırılmış hesapları listele ve tool çağrılarını hesap etiketi ile yönlendir.
Sohbetler ve gruplar: sohbetleri listele, meta verileri incele, grup/kanal oluştur, sohbetlere katıl veya ayrıl, kullanıcıları davet et, yöneticileri yönet, yasakları, varsayılan izinleri, yavaş modu, konuları, davet bağlantılarını, ortak sohbetleri, okundu bilgisini ve mesaj bağlantılarını yönet.
Mesajlar: gönder, zamanla, düzenle, sil, ilet, sabitle, sabitlemeyi kaldır, okundu işaretle, yanıtla, ara, bağlamı incele, anketler oluştur, reaksiyonları yönet, satır içi düğmeleri incele ve satır içi geri çağırıları basıl.
İletişimler: listele, ara, ekle, sil, engelle, engellemeyi kaldır, içe aktar, dışa aktar, doğrudan sohbetleri incele ve son iletişim etkileşimlerini bul.
Medya: dosya gönder, medya indir, dosya yükle, sesli not gönder, etiketler, GIF'ler gönder ve mesaj medyasını incele.
Profil ve gizlilik: kendi hesap bilgilerini al, profil alanlarını güncelle, profil fotoğraflarını ayarla veya sil, gizlilik ayarlarını incele, kullanıcı bilgilerini/fotoğraflarını/durumunu al ve bot komutlarını yönet.
Klasörler ve taslaklar: Telegram klasörlerini listele, oluştur, güncelle, yeniden sırala ve sil; taslakları kaydet, listele ve temizle.

Telegram kullanıcı kontrollü içeriği içeren tüm tool sonuçları sterilize edilmiş ve mümkün olduğunda yapılandırılmış JSON olarak döndürülür.

Gereksinimler

Python 3.10+
my.telegram.org/apps adresinden Telegram API kimlik bilgileri
Telegram oturum dizesi veya dosya tabanlı oturum
Claude Desktop, Cursor veya başka bir MCP uyumlu konak gibi MCP istemci
İsteğe bağlı: yerel geliştirme için uv

Hızlı Başlangıç

Bu sunucuyu uvx telegram-mcp, uvx --from telegram-mcp veya pip install telegram-mcp ile kurma. PyPI üzerindeki telegram-mcp adı şu anda farklı bir proje tarafından sahiplenilmektedir ve bu depoyu kurmaz. TELEGRAM_API_ID, TELEGRAM_API_HASH veya TELEGRAM_SESSION_STRING adını bu pakete iletmek Telegram hesap kimlik bilgilerini alakasız üçüncü taraf koduna açığa çıkarabilir.

1. Klonla ve Yükle

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

2. Oturum Dizesi Oluştur

uv run session_string_generator.py

İstemleri takip et. Oluşturulan oturum dizesini güvenli bir şekilde kaydet.

3. Ortam Değişkenlerini Yapılandır

Örnek dosyayı kopyala ve gerçek değerlerini doldur:

cp .env.example .env

Tek hesaplı kurulum:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING=your_session_string_here

Sunucuyu yerel olarak çalıştır:

uv run main.py

MCP İstemci Yapılandırması

Claude Desktop veya Cursor için MCP sunucusunu bu projenin klonlanmış bir kopyas noktasına yönlendir:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Alternatif olarak, belirli bir release etiketini veya commit'i kullanarak bu depoyu doğrudan GitHub'dan bir sanal ortama yükle:

python -m venv .venv
. .venv/bin/activate
pip install "git+https://github.com/chigwell/telegram-mcp.git@<tag-or-commit>"

Ardından MCP istemcinizi yüklü console script'ini çalıştıracak şekilde yapılandır:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "/full/path/to/.venv/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Depoyu klonlamadan bu depoyu GitHub'dan açıkça kaynak alarak oturum dizesi oluştur:

uvx --from "git+https://github.com/chigwell/telegram-mcp.git@<pinned-release-tag-or-commit>" telegram-mcp-generate-session

Çok Hesaplı Kurulum

Birden fazla Telegram hesabı yapılandırmak için sonek ekli oturum değişkenlerini kullan:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING_WORK=session_string_for_work
TELEGRAM_SESSION_STRING_PERSONAL=session_string_for_personal

Etiketler küçültülür ve toolslarda account parametresi değeri olur.

Tek hesaplı modda, account isteğe bağlıdır.
Çok hesaplı modda, yazma işlemi yapan toollar account gerektirir.
Yalnızca okuma toolları account atlanınca tüm hesaplara yayılır.

Örnek istemi:

"Hesaplarımı listele"
"Tüm hesaplardan okunmamış mesajları göster"
"Bunu iş hesabımdan @example'a gönder"

Proxy Desteği

Telegram trafiğini proxy üzerinden yönlendir ve TELEGRAM_PROXY_* ortam değişkenlerini ayarla. Desteklenen türler socks5, socks4, http ve mtproxy'dir.

SOCKS ve HTTP proxy'leri isteğe bağlı python-socks paketini gerektirir:

uv sync --extra proxy
# veya
pip install python-socks

Tek hesaplı yapılandırma:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USERNAME=optional_user
TELEGRAM_PROXY_PASSWORD=optional_pass
TELEGRAM_PROXY_RDNS=true

MTProxy:

TELEGRAM_PROXY_TYPE=mtproxy
TELEGRAM_PROXY_HOST=mtproxy.example
TELEGRAM_PROXY_PORT=443
TELEGRAM_PROXY_SECRET=ee0123456789abcdef...

Hesap başına geçersiz kılmalar, oturum değişkenleriyle aynı _<LABEL> sonekini kullanır ve soneksiz varsayılanlardan önceliklidir:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080

TELEGRAM_PROXY_TYPE_WORK=http
TELEGRAM_PROXY_HOST_WORK=proxy.work.example
TELEGRAM_PROXY_PORT_WORK=3128

Yanlış yapılandırılmış proxy ayarları (bilinmeyen tür, eksik host/port, geçersiz port, eksik MTProxy sırrı veya eksik python-socks paketi), sunucunun başlangıçta proxy'yi sessizce atlama yerine net bir hata mesajıyla hızlı bir şekilde başarısız olmasına neden olur.

Dosya Yolu Güvenliği

Dosya yolu toolları, izin verilen kökler yapılandırılana kadar devre dışı bırakılır. Bu, send_file, download_media, upload_file, send_voice, send_sticker, set_profile_photo ve edit_chat_photo gibi toolları etkiler.

İzin verilen kökler şu kaynaklardan gelebilir:

Sunucu CLI argümanları, geri dönüş olarak kullanılır.
İstemci tarafından desteklenirse MCP istemci Roots'ları.

Güvenlik davranışı:

İstemci MCP Roots, mevcut olduğunda sunucu CLI köklerini değiştirir.
Boş istemci Roots, hepsini reddet olarak ele alınır.
Yollar gerçek yollar aracılığıyla çözülür ve izin verilen bir kökün içinde kalmalıdır.
Traversal, joker benzeri, shell benzeri ve null bayt yol desenleri reddedilir.
Göreceli yollar ilk izin verilen kök altında çözülür.
İndirmeler varsayılan olarak <first_root>/downloads/ adresine gider.
Boyut ve uzantı sınırları duyarlı medya toolları için uygulanır.

İzin verilen köklerle çalıştır:

uv run main.py /data/telegram /tmp/telegram-mcp

MCP istemci yapılandırmasından, main.py sonrasında aynı kökeri ilet:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py",
        "/data/telegram",
        "/tmp/telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Docker

İmajı oluştur:

docker build -t telegram-mcp:latest .

Compose ile çalıştır:

docker compose up --build

Doğrudan çalıştır:

docker run -it --rm \
  -e TELEGRAM_API_ID="YOUR_API_ID" \
  -e TELEGRAM_API_HASH="YOUR_API_HASH" \
  -e TELEGRAM_SESSION_STRING="YOUR_SESSION_STRING" \
  telegram-mcp:latest

Birden fazla hesap için TELEGRAM_SESSION_STRING_WORK ve TELEGRAM_SESSION_STRING_PERSONAL gibi değişkenleri ilet.

Geliştirme

Uygulama, küçük bir uyumlu giriş noktası ve modüler paket koduna bölünmüştür:

main.py                    # geçmiş giriş noktası ve uyumlu ihraçlar
telegram_mcp/runtime.py    # paylaşılan MCP kurulumu, hesap yönlendirmesi, doğrulama, dosya güvenliği
telegram_mcp/runner.py     # uygulama başlangıcı
telegram_mcp/tools/        # alan başına gruplanmış tool modülleri
sanitize.py                # çıkış sterilizasyon yardımcıları
tests/                     # pytest paketi

Testleri çalıştır:

uv run pytest

Kapsama ile testleri çalıştır:

uv run pytest --cov --cov-report=term-missing --cov-report=xml

Kapsama pyproject.toml içinde yapılandırılmıştır; belirleyici birim sınanabilir çekirdek modüller için %80 minimum kapısı vardır. GitHub Actions aynı kapsama komutunu çalıştırır ve coverage.xml dosyasını yükler.

Biçimlendirme denetimlerini çalıştır:

uv run black --check .
uv run flake8 .

Güvenlik Notları

.env, oturum dizelerini veya .session dosyalarını hiçbir zaman commit etme.
Telegram oturum dizesi, ait olduğu hesaba erişim verir.
PyPI üzerindeki telegram-mcp paket adı bu proje tarafından kontrol edilmez. Mülkiyet değişmediği ve paket doğrulanmadığı sürece PyPI tabanlı telegram-mcp kurulum komutlarından kaçın.
Bu depo, kaynak denetimi olmayan veya doğrudan git/dosya yükleme kaydı olmayan yüklü telegram-mcp dağıtımlarını reddetme konusunda en iyi çabayı sağlayan bir başlangıç koruması içerir. Bu koruması, alakasız PyPI paketi tarafından başlatıldığında çalıştırılamaz; bu nedenle klona dayalı veya açık git yüklemelerini kullan.
Birden fazla sunucu örneği çalıştırırken dosya oturumları üzerinde oturum dizelerini tercih et.
Varsayılan olarak, Telegram API çağrıları makinenizden/kapsayıcınızdan doğrudan Telegram'a gider. TELEGRAM_PROXY_* yapılandırılırsa, Telegram trafiği bunun yerine yapılandırılmış SOCKS/HTTP/MTProxy proxy'si aracılığıyla yönlendirilir.
Kullanıcı tarafından oluşturulan Telegram içeriği MCP istemcilerine döndürülmeden önce sterilize edilir.

İstem Enjeksiyonu Koruması

Telegram mesajları, görünen adlar, sohbet başlıkları ve düğme etiketleri güvenilmeyen içeriktir. Sunucu istem enjeksiyonu riskini şu şekilde azaltır:

Mümkün olduğunca kullanıcı kontrollü veriler için yapılandırılmış JSON çıkışı.
Kontrol karakteri temizlemesi, görünmez karakter temizlemesi ve uzunluk sınırları için sanitize_user_content(), sanitize_name() ve sanitize_dict().
Döndürülen içeriği kullanıcı izleyici verisi olarak işaretleyen MCP içerik ek açıklamaları.
Döndürülen Telegram alanlarını model talimatları olarak ele almamalarını istemcileri uyaran tool açıklamaları.
Kırılgan anahtar sözcük tabanlı filtreleme yok.

Sorun Giderme

Telegram oturumu yapılandırılmadı: TELEGRAM_SESSION_STRING, TELEGRAM_SESSION_NAME veya sonek ekli çok hesaplı varyantlarını ayarla.
Oturum yetkili değil: uv run session_string_generator.py adresini MCP sunucusu dışında çalıştır, mümkün olduğunda QR girişini kullan, ardından .env dosyasında TELEGRAM_SESSION_STRING ayarla. MCP sunucusu stdio üzerinde etkileşimli telefon kodu girişi gerçekleştirmez.
Geçersiz API kimlik bilgileri: my.telegram.org/apps adresinde TELEGRAM_API_ID ve TELEGRAM_API_HASH doğrulaması yap.
Veritabanı kilitli: dize oturumlarını tercih et veya başka hiçbir işlemin aynı dosya oturumunu kullanmadığından emin ol.
Dosya toolları devre dışı: izin verilen kökler ilet veya istemcinde MCP Roots'ları yapılandır.
Yol reddedildi: yolun izin verilen bir kökün içinde olduğundan ve traversal veya joker desenleri kullanmadığından emin ol.
Parola değişikliğinden sonra Auth hatası: oturum dizesini yeniden oluştur.
Bot only aracı reddedildi: normal kullanıcı hesapları bot komut ayarlarını yönetemez.
Ayrıntılara ihtiyaç duy: MCP istemci günlüklerini, terminal çıkışını ve mcp_errors.log adresini kontrol et.

Katkı Yapma

Depoyu fork ve klonla.
Bağımlılıkları ve git hook'larını yükle:
- uv sync
- uv run pre-commit install --hook-type pre-commit --hook-type pre-push
Odaklanmış bir dal oluştur.
Davranış değişikliği olduğunda testler ekle veya güncelle.
Yerel olarak denetimler çalıştır:
- uv run pre-commit run --all-files
- uv run pre-commit run --hook-stage pre-push --all-files
Kısa bir açıklamayla bir pull request aç.

chigwell/telegram-mcp

Bu MCP sunucusu hakkında