itu-mcp

KO | EN

gitlite — search

#php #react-native #reactjs #monitoring #animation #list #rag #macos #tensorflow #privacy

(★ 9)

İTÜ Ninova + OBS’yi Claude, Cursor ve Codex’e bağlayan yerel MCP sunucusu. Ders, ödev, not, transkript ve daha fazlası.

File Explorer

ZIP Download

- - build-mcpb.yml
  - publish.yml
  - tests.yml
- advanced.md
- banner.png
- bu_dönem_hangi_dersler.png
- cli_demo.gif
- installation.md
- logo.gif
- logo.png
- security.md
- son_duyurular.png
- claude_desktop_config.json
- codex_config.toml
- cursor_mcp.json
- openclaw_mcp.json5
- - main.py
- manifest.json
- _bundle_main.js
- _probe_onsart.py
- build_mcpb.py
- - __init__.py
  - __main__.py
  - archive.py
  - archive_client.py
  - attendance_summary.py
  - cache.py
  - client.py
  - community_data.py
  - compact.py
  - env.py
  - gpa.py
  - graduation.py
  - http_security.py
  - library_client.py
  - mail_client.py
  - obs_client.py
  - parsing.py
  - planning.py
  - prerequisites.py
  - prompts.py
  - public_client.py
  - public_parsing.py
  - relative_grading.py
  - remote.py
  - remote_security.py
  - resources.py
  - schedule_utils.py
  - server.py
  - session_store.py
  - text_extract.py
  - tracking.py
- - akademik_takvim.html
  - campus_services.html
  - crosscheck_courses.psv
  - degree_plan.html
  - ders_program.html
  - ders_program_result.html
  - directory_results.html
  - final_exam_result.html
  - ksb_main.html
  - library_pages.html
  - obs_kart_redirect.html
  - odev_gonder.html
  - onsart_ara_cen.html
  - sks_beslenme.html
  - sks_main.html
  - www_ksb_main.html
- test_archive.py
- test_cache.py
- test_cli.py
- test_community_data.py
- test_compact.py
- test_env.py
- test_gpa_fallback.py
- test_gpa_schedule.py
- test_http_security.py
- test_mail_client.py
- test_mcpb_bootstrap.py
- test_obs.py
- test_parsing.py
- test_prompts.py
- test_public_tools.py
- test_relative_grading.py
- test_remote_security.py
- test_remote_tool_allowlist.py
- test_server_cache.py
- test_server_protocol.py
- test_session_store.py
- test_text_extract.py
- test_tool_registry.py
- test_tracking.py
- test_upload.py
.dockerignore
.env.example
.gitattributes
.gitignore
CHANGELOG.md
Dockerfile
LICENSE
MANIFEST.in
mcp-publisher.exe
mcp-publisher.tar.gz
pyproject.toml
README.md
server.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

İTÜ Ninova, OBS, Portal, kampüs servisleri ve kütüphaneyi Claude, Cursor, Codex ve diğer MCP istemcilerine bağla

</div>

---

## İ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](https://modelcontextprotocol.io) üzerinden yapılandırılmış araçlar olarak sunuyor: Claude'a soruyorsun, o da gerçek veriyi çekip cevap veriyor.

| İ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 |
| "Bugün yemekte ne var / kart bakiyem?" | İTÜ Portal menü, kart ve bildirim araçları |
| "Finalim ne zaman / boş kontenjan var mı?" | Public OBS final ve ders programı araçları |
| "Mekik ne zaman / havuz kaçta kapanıyor?" | SKS kampüs hizmeti araçları |
| "Kütüphanede bu kitap var mı?" | Public katalog arama ve kopya durumu |
| "Son okunmamış mailimi göster" | Salt okunur İTÜ Mail araçları |
| "PDF özetle" | İndirme ve `read_resource_text` (PDF/DOCX) |
| "Ödev yükle" | İsteğe bağlı yükleme, `confirm=true` şart |

> **Ö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 tam garanti veremeyiz. Şüpheye düştüğünde her zaman OBS'nin kendi sayfasına bak.

---

## Nasıl çalışır

```mermaid
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"]
```

Sunucu her servise ayrı bir istemci sınıfıyla konuşur, kendi oturumunu ve önbelleğini yönetir. Ninova ve OBS aynı İTÜ SSO girişini paylaşır, kütüphane hesabı bilgisi ise tamamen ayrıdır ve Ninova şifresiyle karışmaz. Kimlik gerektirmeyen araçlar (public ders programı, kampüs servisleri, arşiv) hiçbir zaman şifreni kullanmaz.

Ayrıntılı iç mimari ve istemci sınıfları için: [docs/advanced.md](docs/advanced.md).

---

## Örnekler

<img src="https://raw.githubusercontent.com/yatuk/itu-mcp/main/docs/cli_demo.gif" alt="itu-mcp CLI demo" width="720" />
 
 CLI: <code>--version</code>, <code>--list-tools</code>, <code>--list-prompts</code> (gerçek çıktı)

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

<img src="https://raw.githubusercontent.com/yatuk/itu-mcp/main/docs/bu_d%C3%B6nem_hangi_dersler.png" alt="Bu dönem hangi dersleri aldım" width="720" />
 
 OBS: dönem kayıtlı dersler ve program

<img src="https://raw.githubusercontent.com/yatuk/itu-mcp/main/docs/son_duyurular.png" alt="Son duyurular ve mesajlar" width="720" />
 
 Ninova: son duyurular ve mesaj panosu özeti

---

## Hızlı başlangıç

### 1. Kurulum

```bash
pipx install 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** adresidir, yalnızca yerel kısım değil.

### 3. Duman testi

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

### 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](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."*
- *"Son okunmamış mesajlarımı listele ve seçtiğim PDF ekini özetle."*
- *"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?"*✨
- *"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?"*✨
- *"Kütüphanede Introduction to Algorithms var mı?"*✨

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

---

## Araç haritası

<table>
 <tr>
 <td align="center" width="20%">Ninova oturum gerekir</td>
 <td align="center" width="20%">OBS & Portal oturum gerekir</td>
 <td align="center" width="20%">Public İTÜ kimlik gerekmez ✨</td>
 <td align="center" width="20%">Planlama & Kütüphane karma</td>
 <td align="center" width="20%">Arşiv kimlik gerekmez ✨</td>
 </tr>
 <tr>
 <td>
 <code>auth_status</code> · <code>list_courses</code> 
 <code>get_course_*</code> · <code>sync_all_courses</code> 
 <code>get_upcoming_deadlines</code> 
 <code>read_resource_text</code> · <code>submit_assignment</code>
 </td>
 <td>
 <code>obs_auth_status</code> · <code>obs_get_profile</code> 
 <code>obs_list_registered_courses</code> 
 <code>obs_get_course_grades</code> · <code>obs_get_attendance</code> 
 <code>obs_get_advisor</code> · <code>obs_download_transcript</code> 
 <code>get_cafeteria_menu</code> · <code>obs_get_notifications</code>
 </td>
 <td>
 <code>get_public_course_schedule</code> · <code>get_public_exam_schedule</code> 
 <code>search_itu_directory</code> · <code>search_campus_locations</code> 
 <code>get_shuttle_schedule</code> · <code>get_sports_facility_hours</code> 
 <code>get_itu_announcements</code> · <code>get_academic_calendar</code>
 </td>
 <td>
 <code>obs_calculate_gpa</code> · <code>calculate_target_gpa</code> 
 <code>estimate_relative_grade</code> · <code>check_course_conflicts</code> 
 <code>find_open_course_sections</code> · <code>find_empty_classrooms</code> 
 <code>build_degree_plan</code> · <code>library_*</code>
 </td>
 <td>
 <code>archive_who_taught</code> · <code>archive_course_history</code> 
 <code>archive_fill_rate</code> · <code>archive_term_sections</code> 
 <code>archive_search_courses</code> · <code>plan_remaining_courses</code>
 </td>
 </tr>
 <tr>
 <td colspan="5" align="center">İTÜ Mail (salt okunur): <code>mail_status</code> · <code>mail_list_inbox</code> · <code>mail_get_message</code> · <code>mail_get_attachment</code></td>
 </tr>
</table>

Tam araç listesi, hazır prompt'lar, kaynak tabloları, Docker, uzak HTTP ve tüm ortam değişkenleri: **[docs/advanced.md](docs/advanced.md)**.

Ayrıca `/` menüsünden seçilebilen hazır akışlar var (`weekly_briefing`, `plan_next_term`, `check_course_eligibility`, `research_course`, `gpa_scenario`), her biri hangi araçların hangi sırayla çağrılacağını ve sonucu okurken kaçırılan kuralları içeriyor.

---

## Güvenlik

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

| 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 |
| Kütüphane PIN'ini ayrı `NINOVA_LIBRARY_*` değişkenlerinde tut | Ninova şifresini kütüphane PIN'i olarak tekrar kullanma |
| Harici sayfa metnini **veri** olarak değerlendir | Duyuru/ödev metnindeki modele yönelik talimatları uygulama |
| Uzak kurulumda `NINOVA_REMOTE_API_KEY` kullan | Gizli path ve anahtar olmadan public açma |

Ayrıntılar: [docs/security.md](docs/security.md). OBS profil araçları TCKN ve 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_ALLOW_UPLOADS=1
# 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"
# Ayrı mail kimlik bilgisi (yoksa paylaşılan İTÜ kimliği kullanılır):
# NINOVA_MAIL_USERNAME="ad.soyad@itu.edu.tr"
# NINOVA_MAIL_PASSWORD="mail-sifresi"
```

Tüm değişkenler için `.env.example` ve [docs/advanced.md](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](docs/installation.md) |
| **Gelişmiş / araçlar** | [docs/advanced.md](docs/advanced.md) |
| **Güvenlik** | [docs/security.md](docs/security.md) |
| **Değişiklik günlüğü** | [CHANGELOG.md](CHANGELOG.md) |
| **Sorunlar** | [github.com/yatuk/itu-mcp/issues](https://github.com/yatuk/itu-mcp/issues) |

---

## Teşekkür

Bu proje, [**Hikmet Gultekin**](https://github.com/hikmedit)'in yazdığı orijinal **[ninova-mcp](https://github.com/hikmedit/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.

Salt okunur İTÜ Mail araçlarını (`mail_status`, `mail_list_inbox`, `mail_get_message`, `mail_get_attachment`) [**tzi4**](https://github.com/tzi4) katkı olarak ekledi, teşekkürler.

---

## Lisans

[MIT](LICENSE). İstanbul Teknik Üniversitesi ile resmi bağlantısı yoktur.

<div align="center">
 <a href="https://github.com/yatuk">yatuk</a> tarafından · <a href="https://github.com/yatuk/itu-mcp">GitHub</a>
</div>

itu-mcp

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

itu-mcp

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README