İTÜ MCP

Official

by yatuk · JavaScript

İTÜ Ninova LMS ve OBS öğrenci portalı — dersler, notlar, yoklama, yemekhane, kampüs kart, GPA

README.md10 KBView on GitHub

İTÜ MCP

İTÜ Ninova ve OBS hesabını Claude, Cursor, Codex ve diğer MCP istemcilerine bağla

Sürüm: v0.2.0 Lisans: MIT Python 3.11+ MCP Sunucu

Ninova `LMS`	OBS `Öğrenci portalı`	MCP `Claude · Cursor · Codex`
Dersler · dosyalar · ödevler duyurular · teslim tarihleri	Kayıt · notlar transkript · danışman · staj	Doğal dilde sor (TR / EN)

İTÜ MCP nedir?

İTÜ MCP bilgisayarında çalışır ve kendi İTÜ hesabını yapay zeka asistanlarına bağlar. Kimlik bilgilerinle (genelde ad@itu.edu.tr) giriş yapar, Ninova ve OBS üzerinden veri okur, Model Context Protocol üzerinden yapılandırılmış araçlar sunar.

İhtiyacın	İTÜ MCP cevabı
"Bu hafta hangi ödevlerin teslimi var?"	Ninova ödev ve teslim tarihi araçları
"X dersinin notları / yoklaması?"	OBS ara not, harf notu ve yoklama
"Transkript / danışman / staj?"	OBS profil, danışman, staj, transkript PDF
"PDF özetle"	İndirme + `read_resource_text` (PDF/DOCX)
"Ödev yükle"	İsteğe bağlı yükleme, `confirm=true` şart

Önce yerel. Şifren cihazda kalır; yalnızca İTÜ giriş / Ninova / OBS adreslerine gönderilir. Üçüncü taraf bir sunucuya kimlik bilgisi depolanmaz.

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

Örnekler

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

Bu dönem hangi dersleri aldım
OBS: dönem kayıtlı dersler ve program

Son duyurular ve mesajlar
Ninova: son duyurular ve mesaj panosu özeti

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"]
        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)"]
    end

    istemciler -->|"MCP araçları"| mcp
    mcp --> ninova_client
    mcp --> obs_client
    mcp --> obs_public
    ninova_client --> giris
    ninova_client --> ninova
    obs_client --> giris
    obs_client --> obs
    obs_public --> obs_pub
    ninova_client --> state
    obs_client --> state
    obs_public --> state

Katman	Rol
MCP sunucu	Araç listesi, sade yanıtlar, CLI (`--check-auth`, `--list-tools`)
Ninova istemcisi	Oturum + HTML ayrıştırma (duyuru, dosya, ödev, yükleme formu)
OBS istemcisi	SSO → `/ogrenci/auth/jwt` → `/api/ogrenci/...`
OBS public istemcisi	Kimliksiz → `/public/DersProgram`, `/public/DersBilgi`, `/public/GenelTanimlamalar/...`
Durum	İsteğe bağlı çerez önbelleği, izleme anlık görüntüleri, indirmeler (`~/.ninova_state`)

Hızlı başlangıç

1. Kurulum

bash

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

bash

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

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

3. Duman testi

bash

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

4. MCP istemcisini bağla

Claude Code

bash

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

Codex CLI

bash

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.

Bitti. İ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."
"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?"^✨

^✨ _{Kimlik gerektirmez — .env olmadan da çalışır.}

Araç haritası

Ninova (LMS) _{oturum gerekir}	OBS (portal) _{oturum gerekir}	OBS Public _{kimlik gerekmez ✨}
`auth_status` · `list_courses` `get_course_*` · `sync_all_courses` `get_upcoming_deadlines` `read_resource_text` · `submit_assignment`	`obs_auth_status` · `obs_get_profile` `obs_list_registered_courses` `obs_get_course_grades` · `obs_get_attendance` `obs_get_advisor` · `obs_download_transcript` `obs_get_schedule` · `obs_get_internships`	`obs_search_courses` `obs_get_course_prerequisites` `get_public_course_schedule` `get_public_course_prerequisites`

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

Güvenlik

Yap	Yapma
Yalnızca kendi İTÜ hesabını kullan	`.env` veya çerezleri commit etme
Yerel stdio MCP tercih et	Uzak MCP URL / API anahtarını paylaşma
`submit_assignment` yalnızca `confirm=true` ile	Önizlemeyi okumadan ödev yükleme
Uzak kurulumda `NINOVA_REMOTE_API_KEY` kullan	Gizli path ve anahtar olmadan public açma

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ı)

bash

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

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

Geliştirme

bash

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

Kaynak	URL
Kurulum	docs/installation.md
Gelişmiş / araçlar	docs/advanced.md
Güvenlik	docs/security.md
Değişiklik günlüğü	CHANGELOG.md
Sorunlar	github.com/yatuk/itu-mcp/issues

Teşekkür

Bu proje, Hikmet Gultekin tarafından yazılan orijinal ninova-mcp çalışmasının üzerine kurulmuştur. İlk açık kaynak, kimlik bilgisiyle çalışan İTÜ Ninova MCP sunucusudur (LMS giriş, HTML ayrıştırma, izleme, .mcpb paketleme).

İTÜ MCP bu temeli genişletir: OBS öğrenci portalı API'leri, PDF metin okuma, güvenli ödev yükleme, oturum kalıcılığı, uzak API anahtarı ve bu depo altında yeniden paketleme.

Lisans

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

_{yatuk tarafından · GitHub}

Install

Configuration

Environment variables

NINOVA_USERNAMErequired

İTÜ e-posta adresi (ad.soyad@itu.edu.tr)

NINOVA_PASSWORDrequiredsecret

İTÜ şifresi

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "itu-mcp": {
      "command": "uvx",
      "args": [
        "itu-mcp"
      ],
      "env": {
        "NINOVA_USERNAME": "<YOUR_NINOVA_USERNAME>",
        "NINOVA_PASSWORD": "<YOUR_NINOVA_PASSWORD>"
      }
    }
  }
}