Bu ne işe yarıyor?

Ödev için Ninova'ya, not için OBS'ye, yemek için Portal'a girmek yerine asistanına yazıyorsun, o da gerçek veriyi çekip cevaplıyor.

İTÜ MCP bilgisayarında çalışan küçük bir programdır. Claude, Cursor veya Codex gibi bir asistana İTÜ sistemlerini okuma yeteneği kazandırır. Kod yazmayı bilmen gerekmez, kurup soru sorman yeterli.

Şifren bilgisayarından çıkmaz. Program yalnızca İTÜ'nün kendi sunucularıyla konuşur.
İstanbul Teknik Üniversitesi ile resmi bir bağlantısı yoktur.

3 adımda kur

Python 3.11 veya üstü gerekir. Yüklü değilse python.org adresinden kurabilirsin.

1. Programı kur

pipx install itu-mcp

pipx yoksa pip install --user itu-mcp da olur.

2. Asistanına bağla

Claude Code kullanıyorsan tek komut yeter. Kendi İTÜ e-postanı ve şifreni yaz:

claude mcp add itu itu-mcp -e [email protected] -e NINOVA_PASSWORD=sifren

Codex CLI

codex mcp add itu --env [email protected] --env NINOVA_PASSWORD=sifren -- itu-mcp

Claude Desktop ve Cursor için hazır ayar dosyaları examples/ klasöründe. Adım adım anlatım: docs/installation.md.

3. Sor

Asistanı yeniden başlat ve yaz:

Ninova'daki derslerimi listele

Bir liste geldiyse kurulum tamam.

Önce programın kendisini dene:

itu-mcp --version
itu-mcp --check-auth

• --check-auth hata veriyorsa kullanıcı adını tam e-posta olarak yazdığından emin ol ([email protected], yalnızca ad.soyad değil).
• Komut bulunamıyorsa terminali kapatıp yeniden aç. pipx kurulumdan sonra yeni bir terminal ister.
• Asistan aracı görmüyorsa asistanı tamamen kapatıp açmayı dene.
• Hâlâ olmuyorsa bir sorun kaydı aç, ekran çıktısını ekle. Şifreni yazma.

Şifre vermek istemiyor musun? Ders programı, final tarihleri, not dağılımları, ders arşivi, mekik saatleri ve kütüphane kataloğu gibi herkese açık bilgiler şifresiz de çalışır. İkinci adımdaki -e kısımlarını silmen yeterli.

Neler sorabilirsin?

Aşağıdakiler Claude Code'a yazılmış örnek sorular. Sen kendi cümlelerinle sorabilirsin, hangi aracın çağrılacağını asistan seçer. Çıktılar örnektir, sende kendi verin görünür.

> Bu hafta hangi ödevlerimin teslimi var?

● itu · get_upcoming_deadlines

Bu hafta 2 teslimin var:

  BLG 223E  Ödev 3
            Perşembe 23:59, 2 gün kaldı
            Henüz yüklenmemiş

  MAT 210E  Proje raporu
            Pazar 23:59, 5 gün kaldı
            Yüklendi

> BLG 223E geçen güz nasıl geçmiş?

● itu · archive_grade_distribution

2025-2026 Güz, 176 öğrenci:

  AA   9      CC+  19
  BA+ 12      CC   21
  BB+ 18      FF   38

En kalabalık not FF (38 kişi).
AA alan 9 kişi var.

> 12469, 12554 ve 12583 CRN'leri
  çakışıyor mu?

● itu · check_course_conflicts

1 çakışma buldum:

  Salı 08:30-10:29
  BLG 223E ile BLG 345E üst üste

12583 (BLG 422E) sorunsuz.
BLG 345E için başka şube arayayım mı?

> BLG 335E'yi bu dönem alabilir miyim?

● itu · explain_course_eligibility

Henüz alamazsın.

  Gereken:  BLG 223E (en az DD)
  Durumun:  BLG 223E bu dönem kayıtlı,
            notu açıklanmamış

BLG 223E'yi geçersen gelecek dönem
açılıyor.

> Bugün yemekte ne var, mekik kaçta?

● itu · get_cafeteria_menu
● itu · get_shuttle_schedule

Öğle yemeği:
  Mercimek çorbası, tavuk sote,
  pirinç pilavı, sütlaç

Ayazağa'dan sonraki mekik 13:30.

> Bu dönem hepsinden BB alırsam
  ortalamam kaç olur?

● itu · obs_calculate_gpa

Şu anki GANO:      2.84
Dönem tahmini:     3.00
Dönem sonu GANO:   2.89

Bu bir tahmin, resmi ortalama
OBS'de açıklanır.

Daha fazla fikir:

• "EEF 211E sınıf dosyalarındaki son PDF'i özetle."
• "Danışmanım kim, staj durumum ne?"
• "Transkriptimi indir."
• "BBB binasında şu an boş derslik var mı?"
• "BLG 223E'yi geçersem hangi dersler açılır?"
• "Mezuniyetime kaç ders kaldı, gelecek dönem hangilerini almalıyım?"
• "Kütüphanede Introduction to Algorithms var mı?"
• "Son okunmamış maillerimi listele, ekindeki PDF'i özetle."

Asistanın / menüsünde hazır akışlar da var: weekly_briefing (haftalık özet), plan_next_term (gelecek dönem planı), registration_week (kayıt haftası kontrolü), check_course_eligibility, research_course ve gpa_scenario.

Sık sorulanlar

Hiçbir yere. Program senin bilgisayarında çalışır ve şifreni yalnızca İTÜ'nün kendi giriş sayfasına gönderir, tıpkı tarayıcının yaptığı gibi. Arada bizim ya da başkasının bir sunucusu yoktur. Kod açık, istersen kendin bakabilirsin.

Hayır. Öğrenciler tarafından yazılmış açık kaynak bir projedir, İTÜ ile resmi bağlantısı yoktur. Yalnızca kendi hesabınla kullan.

Neredeyse her şey yalnızca okur. İki istisna var ve ikisi de senin açık onayın olmadan çalışmaz:

• Ödev yükleme. Önce neyi nereye yükleyeceğini gösterir, sen onaylayınca yükler.
• Kayıt taslağı kaydetme. Varsayılan olarak kapalıdır. Açsan bile taslaktan ders silinecekse durur ve sana sorar.

İkisinde de, asistanın destekliyorsa, program göndermeden hemen önce sana doğrudan bir onay penceresi açar: hangi dosya, hangi ödev, hangi CRN'ler yazılacak, hangileri taslaktan çıkacak. Asistanın kendi kendine "onaylıyorum" demesi bu pencereyi atlatamaz. Onaylamazsan hiçbir şey gönderilmez.

Ders kaydı yapmaz, ders bırakmaz, mail göndermez.

Veriyi doğrudan İTÜ sistemlerinden çeker, uydurmaz. Yine de OBS bazı bilgileri hesaba göre farklı döndürebiliyor. Bir veri eksikse araç bunu açıkça söyler. Kayıt, mezuniyet ve not gibi önemli kararlarda son sözü her zaman OBS'nin kendi sayfası söyler.

MCP destekleyen her istemciyle: Claude Code, Claude Desktop, Cursor, Codex ve benzerleri. ChatGPT ya da Claude.ai gibi web arayüzleri için uzak sunucu kurulumu gerekir, anlatımı docs/advanced.md içinde.

Kısmen. Dolu bir şubenin CRN'ini izleme listesine ekleyebilirsin (watch_course_sections), sonra "izlediğim şubelerde yer açıldı mı" diye sorduğunda son kontrolden bu yana ne değiştiğini söyler. Giriş gerektirmez.

Ama program arka planda çalışmaz ve kendiliğinden bildirim göndermez. Kontenjan yalnızca sen sorduğunda okunur. Düzenli takip istiyorsan asistanında birkaç dakikada bir bu soruyu soran zamanlanmış bir görev kurman gerekir.

Evet. Araçlar gruplara ayrılmış durumda ve her aracın tanımı sohbetin başında asistana yüklenir. Kullanmadığın grupları kapatırsan asistan doğru aracı daha kolay seçer.

NINOVA_TOOLSETS=ninova,obs,archive        # yalnızca bu gruplar açık olsun
NINOVA_DISABLED_TOOLSETS=library,mail     # ya da: bunlar dışında her şey açık olsun

Gruplar: core, ninova, files, obs, registration, portal, planning, public, campus, library, archive, mail. İkisini de yazmazsan her şey açık kalır. Hangi grupta ne olduğunu itu-mcp --list-toolsets gösterir.

Hayır. MIT lisanslı, tamamen ücretsiz. Yalnızca kullandığın asistanın kendi ücreti varsa o geçerlidir.

Nasıl çalışır?

graph LR
    istemci["Claude, Cursor, Codex"] -->|"MCP"| sunucu["İTÜ MCP"]
    sunucu --> ninova["Ninova"]
    sunucu --> obs["OBS"]
    sunucu --> portal["Portal"]
    sunucu --> kutuphane["Kütüphane"]
    sunucu --> arsiv["Ders Arşivi"]
    sunucu --> mail["İTÜ Mail"]

Asistan bir soru aldığında İTÜ MCP'deki uygun aracı çağırır. Araç ilgili İTÜ sistemine gider, cevabı düzenli bir biçimde geri verir, asistan da bunu sana anlatır. Ninova ve OBS aynı İTÜ girişini kullanır. Şifre gerektirmeyen araçlar şifreni hiç kullanmaz.

Her aracın ne yaptığı, parametreleri ve sınırları: docs/advanced.md. Kayıt planlama araçları için docs/registration-planning.md, not dağılımları için docs/grade-distribution.md.

Çoğu kişinin hiçbir ayara dokunması gerekmez. İstersen şunları ortam değişkeni olarak verebilirsin:

NINOVA_SESSION_PERSIST=1            # girişi hatırla (varsayılan açık)
NINOVA_ALLOW_UPLOADS=1              # ödev yüklemeye izin ver (0 yaparsan kapanır)
NINOVA_OBS_REGISTRATION_WRITES=1    # kayıt taslağı kaydetmeyi aç (varsayılan kapalı)
NINOVA_REQUIRE_ELICITATION=1        # onay penceresi gösteremeyen asistanlarda yazma işlemini reddet
NINOVA_ALLOW_SENSITIVE_OUTPUT=1     # TCKN, telefon, adres ve adların gizlenmeden dönmesine izin ver (varsayılan kapalı)
NINOVA_EXTRA_READ_DIRS=...          # asistanın okuyabileceği ek klasörler (tam yol)
NINOVA_EXTRA_DOWNLOAD_DIRS=...      # indirmelerin yazılabileceği ek klasörler (tam yol)
NINOVA_MAX_DOWNLOAD_MB=200          # tek indirme için boyut sınırı
NINOVA_TOOLSETS=ninova,obs,archive  # yalnızca bu araç gruplarını aç
NINOVA_MAIL_USERNAME=...            # mail için ayrı kullanıcı adı
NINOVA_MAIL_PASSWORD=...            # mail için ayrı şifre

.env dosyası yalnızca sunucunun başlatıldığı klasörde aranır, üst klasörlere bakılmaz. Başka bir dosya için NINOVA_ENV_FILE değişkenine tam yolu yaz. O klasördeki .env kullanıcı adı ve şifre gibi değerleri verebilir ama adres, sunucu, klasör ve yazma izni gibi güvenlikle ilgili ayarları değiştiremez. Bunları asistanının env bloğunda ya da NINOVA_ENV_FILE ile gösterdiğin dosyada ver.

Tam liste .env.example dosyasında ve docs/advanced.md içinde. Kütüphane kataloğu ve proxy ayarı için docs/library-catalog.md.

Güvenlik

Bilmen gereken sınırlar:

• Adres alan araçlar (read_page, download_resource ve benzerleri) yalnızca ninova.itu.edu.tr adreslerini kabul eder. OBS, Portal ve yardım talepleri için kendi araçları var.
• OBS profil araçları TCKN ve telefonu, yardım talebi aracı kişi adlarını gizler. Asistan istese bile bunlar ancak sen NINOVA_ALLOW_SENSITIVE_OUTPUT=1 ayarladıysan görünür.
• İTÜ Mail araçları yalnızca imap.itu.edu.tr sunucusuna, 993 numaralı porttan bağlanır.
• Uzak HTTP sunucusu (itu-mcp-remote) 127.0.0.1 dışında bir adrese bağlanıyorsa (Docker imajı dahil) NINOVA_REMOTE_API_KEY ve NINOVA_ALLOWED_HOSTS ya da NINOVA_PUBLIC_BASE_URL verilmeden çalışmaz, eksik değişkeni yazıp kapanır. Yerelde anahtar vermezsen her açılışta rastgele bir anahtar üretir ve bir kez ekrana yazar.

Ayrıntılar: docs/security.md ve docs/advanced.md.

Geliştirme

Katkıya açık. Bir hata bulduysan ya da bir fikrin varsa sorun kaydı aç.

git clone https://github.com/yatuk/itu-mcp.git
cd itu-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -e ".[playwright]"
python -m pytest tests/ -q
python -m ruff check src/ tests/

Teşekkür

Bu proje, Hikmet Gultekin'in yazdığı orijinal ninova-mcp üzerine kuruldu. İlk açık kaynak, kimlik bilgisiyle çalışan İTÜ Ninova MCP sunucusudur.

tzi4 salt okunur İTÜ Mail araçlarını, kayıt planlama ve not dağılımı araçlarını, yardım talebi detaylarını ve OBS tarafındaki pek çok düzeltmeyi katkı olarak ekledi. Teşekkürler.

Lisans

MIT. İstanbul Teknik Üniversitesi ile resmi bağlantısı yoktur.