itu-mcp

İTÜ MCP nedir?

Ninova'da ödev, OBS'de not, Portal'da yemek listesi diye üç ayrı sekmede gezinmek can sıkıcı. İTÜ MCP bilgisayarında çalışan küçük bir sunucu, bu sekmelerin hepsini tek bir yerden, doğal dilde sorulabilir hale getiriyor.

Kimlik bilgilerinle (genelde ad@itu.edu.tr) Ninova, OBS ve Portal verilerini okuyor. Kimlik bilgisi olmadan da ders/final programı, bina kodları, mekik, spor tesisi, duyuru ve kütüphane kataloğu gibi herkese açık kaynaklara erişiyor. Sonuçları Model Context Protocol üzerinden yapılandırılmış araçlar olarak sunuyor: Claude'a soruyorsun, o da gerçek veriyi çekip cevap veriyor.

Önce yerel. Ninova şifren cihazda kalır, yalnızca İTÜ SSO, Ninova, OBS ve Portal akışlarında kullanılır. Ayrı kütüphane hesabı bilgileri yalnızca resmî kütüphane sunucusuna gönderilir. Üçüncü taraf bir sunucuya kimlik bilgisi depolanmaz.

İTÜ ile resmi bağlantısı yoktur. Yalnızca kendi hesabınla kullan.

Dürüst olmak gerekirse OBS'nin bazı uç noktaları hesaba göre tutarsız davranabiliyor (bir hesapta not alanı boş dönerken başka bir hesapta doluyor gibi). Böyle durumları elimizden geldiğince yakalayıp yedek kaynağa düşüyoruz ve sonucu açıkça işaretliyoruz, ama %100 garanti veremeyiz. Şüpheye düştüğünde her zaman OBS'nin kendi sayfasına bak.

Related MCP server: Ninova MCP

Örnekler

Claude Desktop üzerinden doğal dilde soru sorma örnekleri:

Mimari

flowchart LR
    subgraph istemciler["MCP İstemcileri"]
        claude["Claude Desktop"]
        claude_code["Claude Code"]
        cursor["Cursor"]
        codex["Codex"]
    end

    subgraph sunucu["itu-mcp (Python 3.11+)"]
        mcp["MCP Sunucu<br/>(FastMCP · stdio / HTTP)"]
        ninova_client["NinovaClient<br/>SSO · HTML parse"]
        obs_client["ObsClient<br/>JWT · JSON API"]
        obs_public["ObsPublicClient<br/>kimliksiz · HTML/JSON"]
        itu_public["ItuPublicClient<br/>exact host allowlist · kimliksiz"]
        library_client["LibraryClient<br/>ayrı katalog/hesap oturumu"]
        archive_client["ItuArchiveClient<br/>kimliksiz · statik JSON arşiv"]
        state["Durum<br/>çerez · anlık görüntü · indirme"]
    end

    subgraph itu["İTÜ Sunucuları"]
        ninova["ninova.itu.edu.tr<br/>(LMS · HTML)"]
        giris["girisv3.itu.edu.tr<br/>(İTÜ SSO giriş)"]
        obs["obs.itu.edu.tr<br/>(öğrenci JSON API)"]
        obs_pub["obs.itu.edu.tr/public<br/>(açık katalog · program)"]
        portal["portal.itu.edu.tr<br/>(kart · yemek · bildirim)"]
        campus["rehber · SKS · ÖDEK · İKM · Erasmus"]
        library["divit.library.itu.edu.tr<br/>(WebPAC)"]
    end

    subgraph arsiv["Ders Arşivi"]
        archive["yatuk.github.io/itu-archive<br/>(27 dönem · günlük tarama)"]
    end

    istemciler -->|"MCP araçları"| mcp
    mcp --> ninova_client
    mcp --> obs_client
    mcp --> obs_public
    mcp --> itu_public
    mcp --> library_client
    mcp --> archive_client
    ninova_client --> giris
    ninova_client --> ninova
    obs_client --> giris
    obs_client --> obs
    obs_client --> portal
    obs_public --> obs_pub
    itu_public --> obs_pub
    itu_public --> campus
    library_client --> library
    archive_client --> archive
    ninova_client --> state
    obs_client --> state
    obs_public --> state
    library_client --> state

Hızlı başlangıç

1. Kurulum

pipx install itu-mcp
# veya: pip install --user itu-mcp
# kaynaktan:
#   git clone https://github.com/yatuk/itu-mcp.git
#   cd itu-mcp && pip install -e .

2. Kimlik bilgileri

cp .env.example .env
# NINOVA_USERNAME=ad.soyad@itu.edu.tr
# NINOVA_PASSWORD=********

Kullanıcı adı genelde İTÜ e-posta adresidir, yalnızca yerel kısım değil.

3. Duman testi

itu-mcp --version
itu-mcp --check-auth
itu-mcp --list-tools
itu-mcp --list-prompts

4. MCP istemcisini bağla

Claude Code

claude mcp add itu itu-mcp \
  -e NINOVA_USERNAME=ad.soyad@itu.edu.tr \
  -e NINOVA_PASSWORD=sifren

Codex CLI

codex mcp add itu \
  --env NINOVA_USERNAME=ad.soyad@itu.edu.tr \
  --env NINOVA_PASSWORD=sifren \
  -- itu-mcp

Claude Desktop / Cursor: docs/installation.md ve examples/ klasörüne bak.

Bu kadar. İstemciyi yeniden başlat ve sor: "Ninova'daki derslerimi listele" veya "OBS'te bu dönem kayıtlı derslerim?"

Ne sorabilirsin?

• "Bu hafta hangi ödevlerimin teslimi var?"

• "EEF 211E sınıf dosyalarındaki PDF'i oku."

• "OBS'te 2025-2026 Bahar kayıtlı derslerim neler?"

• "CEN 354E ara notlarım?"

• "Danışmanım kim? Staj bilgilerimi göster."

• "Transkript PDF indir."

• "Gelecek dönem hangi dersleri almalıyım?"✨

• "Vizeden 63 aldım, sınıf 30,35,40...90 arası dağılmış, hangi harf notunu alırım?"✨

• "BLG bölümünde bu dönem hangi dersler açılmış, kontenjan durumu ne?"✨

• "BLG 223E'yi almak için önce hangi dersleri almam lazım?"✨

• "BLG final programı açıklandı mı?"✨

• "BBB binası neresi, bugün 10:00'da hangi derslikler boş görünüyor?"✨

• "İTÜ mekik saatleri ve yüzme havuzu çalışma saatleri?"✨

• "ÖDEK ve İKM'deki son duyuruları göster."✨

• "Kütüphanede Introduction to Algorithms var mı?"✨

✨ Kimlik gerektirmez, .env olmadan da çalışır.

Araç haritası

Tam araç listesi, Docker, uzak HTTP, ortam değişkenleri: docs/advanced.md.

Hazır akışlar (prompts)

Claude Desktop'ta / menüsünden seçilen hazır şablonlar. Her biri hangi araçların hangi sırayla çağrılacağını, sonucu okurken kolayca kaçırılan kuralları içeriyor. Yani prompt'u seçtiğinde model aynı hataları tekrar tekrar yapmıyor.

Sabit referans tabloları (resources)

Arşiv araçları

OBS yalnızca aktif dönemi gösteriyor. Dönem bitince veri de gidiyor. İTÜ Ders Arşivi 2016-2017 Yaz'dan bu yana her dönemi saklıyor, İTÜ MCP de onu canlı OBS verisinin yanında okuyor: kayıt durumun artık geçmiş dönemlerin bağlamıyla birlikte geliyor.

Arşiv sonuçları coverage alanı taşır: boş sonuç "ders açılmadı" değil, "o dönem hiç kaydedilmemiş" ya da "o branş dökümde yok" anlamına da gelebilir. Araç bu üçünü ayrı ayrı bildirir.

Ortalama ve harf notu araçları

obs_calculate_gpa OBS'teki kayıtlı derslerinden GANO'nu hesaplıyor, hipotetik notlarla ("BLG 223E'den AA alırsam?") senaryo da kurabiliyorsun. estimate_relative_grade ise ayrı bir soruyu cevaplıyor: sınav henüz notlanmadan, sınıfın ham puanlarını ve kendi puanını verirsen İTÜ'nün bağıl değerlendirme yönetmeliğindeki iki resmi yönteme göre (T-skoru ve ortalama ± standart sapma) muhtemel harf notunu tahmin ediyor. İki yöntem bazen farklı sonuç verir, ikisini de gösteriyoruz. Bunun tahmin olduğunu, resmi notun öğretim üyesine ait olduğunu unutma.

Güvenlik

Kendi hesabını kullanıyorsun, o yüzden şuna dikkat et:

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

OBS profil araçları TCKN / telefonu varsayılan olarak gizler (include_sensitive=true ile açılır).

Yapılandırma (isteğe bağlı)

export NINOVA_COURSE_CACHE_TTL_SECONDS=60
export NINOVA_REQUEST_DELAY_MS=120
export NINOVA_SESSION_PERSIST=1
export NINOVA_COMPACT_DEFAULT=0
export NINOVA_ALLOW_UPLOADS=1
export NINOVA_OBS_BASE_URL=https://obs.itu.edu.tr
export NINOVA_OBS_PUBLIC_CACHE_TTL_SECONDS=3600
export NINOVA_PUBLIC_SCHEDULE_CACHE_TTL_SECONDS=60
export NINOVA_ITU_PUBLIC_CACHE_TTL_SECONDS=300
export NINOVA_LIBRARY_CACHE_TTL_SECONDS=300
# Kütüphane hesabı araçları için (public katalog araması bunları istemez):
# NINOVA_LIBRARY_NAME="Soyad, Ad"
# NINOVA_LIBRARY_ID="öğrenci-numarası"
# NINOVA_LIBRARY_PIN="ayrı-kütüphane-pin'i"

Kütüphane istemcisi TLS doğrulamasını kapatmaz, katalog sertifikası geçersizse güvenli biçimde hata verir. Kurumsal bir CA gerekiyorsa NINOVA_LIBRARY_CA_BUNDLE ile güvenilen sertifika paketini açıkça gösterebilirsin.

.env.example ve docs/advanced.md dosyalarına bak.

Geliştirme

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 unittest discover -s tests -v

Bağlantılar

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 (LMS giriş, HTML ayrıştırma, izleme, .mcpb paketleme).

İTÜ MCP bunun üzerine OBS öğrenci portalı API'lerini, PDF metin okumayı, güvenli ödev yüklemeyi, oturum kalıcılığını, uzak API anahtarını ve arşiv/prompt/resource desteğini ekliyor.

Lisans

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