mcpField
İ
İTÜ MCP

İTÜ MCP

本地服务
github.com科研与教育141 天前更新
代码仓库访问官网

关于 İTÜ MCP

İTÜ MCP 是面向伊斯坦布尔技术大学学生的开源 MCP 服务，可在本机读取 Ninova、OBS、Portal、图书馆及课程档案等校内系统。它以只读访问为主，并对少数会修改数据的操作要求确认。

主要功能

  1. 01读取 Ninova 课程与作业
  2. 02查询 OBS 成绩、课表与注册状态
  3. 03访问 Portal、图书馆和课程档案
  4. 04规划课程并计算 GPA 情景
  5. 05邮件只读查询与附件读取
  6. 06按工具组筛选功能

适用场景

  1. 01汇总本周作业截止日期
  2. 02检查课程冲突与选课资格
  3. 03估算成绩对 GPA 的影响
  4. 04查询图书馆藏书和校园班车时刻

MCP 相关

作为本地运行的 MCP 服务，它连接支持 MCP 的客户端与 İTÜ 系统，并将查询工具提供给 AI 助手。大多数工具只读；上传作业和保存注册草稿等修改操作需明确确认。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "yatuk-itu": {
      "command": "uvx",
      "args": [
        "itu-mcp"
      ],
      "env": {
        "NINOVA_USERNAME": "<NINOVA_USERNAME>",
        "NINOVA_PASSWORD": "<NINOVA_PASSWORD>",
        "NINOVA_MAIL_USERNAME": "<NINOVA_MAIL_USERNAME>",
        "NINOVA_MAIL_PASSWORD": "<NINOVA_MAIL_PASSWORD>",
        "NINOVA_LIBRARY_NAME": "<NINOVA_LIBRARY_NAME>",
        "NINOVA_LIBRARY_ID": "<NINOVA_LIBRARY_ID>",
        "NINOVA_LIBRARY_PIN": "<NINOVA_LIBRARY_PIN>"
      }
    }
  }
}
启动命令uvx itu-mcp
需要配置的环境变量
NINOVA_USERNAMEİTÜ e-posta adresi ([email protected])
NINOVA_PASSWORD密钥İTÜ şifresi
NINOVA_MAIL_USERNAMEOptional separate ITU Mail username
NINOVA_MAIL_PASSWORD密钥Optional separate ITU Mail password
NINOVA_LIBRARY_NAMEKütüphane hesabındaki ad (hesap araçları için isteğe bağlı)
NINOVA_LIBRARY_ID密钥Kütüphane üniversite numarası (hesap araçları için isteğe bağlı)
NINOVA_LIBRARY_PIN密钥Ayrı kütüphane PIN'i (hesap araçları için isteğe bağlı)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypiitu-mcp1.4.0

工具

111

收录的工具列表 · 更新于 1 天前

此工具无需参数。

详细介绍

İTÜ MCP

将 Ninova、OBS、Portal、图书馆和课程档案连接到 AI 助手。然后只管提问。

版本：v1.2.1 许可证：MIT Python 3.11+ MCPRadar 安全性 MCP 服务

安装 · 示例 · 常见问题 · 全部工具

İTÜ MCP 演示视频

带声音的全分辨率版本：docs/demo.mp4

英文版

İTÜ MCP 是一个非官方、开源的 Model Context Protocol 服务，面向伊斯坦布尔技术大学（İTÜ）的学生。它在你自己的电脑上运行，让 Claude、ChatGPT、Cursor 或 Codex 等 AI 助手帮你读取 İTÜ 的系统：Ninova LMS（课程、作业、文件、公告）、İTÜ Moodle 和物理、化学、数学公共课程网站（教学大纲、指南、公告）、OBS（成绩、课表、注册状态、成绩单、毕业进度）、学生 Portal、图书馆目录，以及往年课程开设情况的公开档案。

  • 用自然语言提问：“这周有哪些截止的作业”“如果所有课都拿 BB，我的 GPA 会是多少”“MAT 210E 哪些班还有名额”。
  • 默认只读。两项会更改内容的操作（上传作业、保存选课草稿）都会先征求你的确认。
  • İTÜ 密码保存在你的电脑上，只会发送到 İTÜ 自己的登录页面。
  • 使用 pipx install itu-mcp 安装，或将其作为插件添加到 Claude Code：claude plugin marketplace add yatuk/itu-mcp。

本页其余内容为土耳其语。安装方法：3 adımda kur。完整工具列表：docs/advanced.md。安全模型：docs/security.md。本项目与 İTÜ 无关。

这有什么用？

不用为了作业登录 Ninova、为了成绩登录 OBS、为了查看伙食登录 Portal，只要给助手发消息，它就会获取真实数据并回答。

İTÜ MCP 是一个在你电脑上运行的小程序。它让 Claude、Cursor 或 Codex 等助手能够读取 İTÜ 系统。你不需要会编程，只要安装好并提问即可。

你输入它查询
“我这周有哪些作业？”Ninova
“期中考试成绩公布了吗？”OBS
“今天有什么饭菜？”Portal
“去年谁教了这门课，有多少人拿到 AA？”课程档案
“图书馆有这本书吗？”图书馆目录
“帮我找一些关于睡眠与学业成绩的论文，用于我的作业”论文索引、图书馆数据库
“总结一下我未读的邮件”İTÜ Mail
“读取 FIZ 102E 的教学大纲和公告”Moodle 和公共课程网站
“这个班有空位时通知我”名额追踪
“把我的课表添加到手机日历”日历文件（.ics）

你的密码不会离开电脑。程序只与 İTÜ 自己的服务端通信。 本项目与伊斯坦布尔技术大学没有官方关联。

3 步完成安装

需要 Python 3.11 或更高版本。如果尚未安装，可以从 python.org 安装。

1. 安装程序

pipx install "itu-mcp[keyring]"

如果没有 pipx，也可以运行 pip install --user "itu-mcp[keyring]"。

2. 保存登录信息并连接到助手

itu-mcp setup

itu-mcp connect

itu-mcp setup 会询问你的 İTÜ 邮箱和密码。输入密码时，屏幕上不会显示，也不会写入任何文件，而是保存到操作系统的钥匙串（Windows 凭据管理器、macOS 钥匙串、Linux 上的 GNOME Keyring 或 KWallet）。

itu-mcp connect 会将服务以无密码方式添加到 Claude Desktop、Claude Code 和 Cursor 的设置中。它不会改动其他设置，并会备份文件。想先查看它将执行什么操作，可以运行 itu-mcp connect --dry-run。如果只想连接一个助手：itu-mcp connect claude-desktop（或 claude-code、cursor）。

我不想使用钥匙串，或者我在使用 Codex

你也可以手动将密码写入助手的设置中。

Claude Code

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 和 Cursor 的预设设置文件位于 examples/ 文件夹中。分步说明：docs/installation.md。

3. 提问

重启助手并输入：

Ninova'daki derslerimi listele

如果出现列表，说明安装完成。

没有成功，该怎么办？

先运行：

itu-mcp doctor

每一行都以 OK、UYARI 或 HATA 开头，非 OK 的行下方会写明解决方法。想要同时测试登录，可以运行 itu-mcp doctor --online。

  • 如果登录出错，请确认用户名填写的是完整邮箱（[email protected]，而不仅是 ad.soyad）。
  • 如果找不到命令，请关闭并重新打开终端。安装 pipx 后需要打开一个新终端。
  • 如果助手看不到工具，请尝试完全关闭并重新打开助手。
  • 如果仍然不行，请提交问题，并附上屏幕输出。不要填写密码。

不想提供密码？ 课程表、期末考试日期、成绩分布、课程档案、班车时刻表和图书馆目录等公开信息无需密码也能使用。跳过 itu-mcp setup 步骤，只运行 itu-mcp connect 即可。

可以问些什么？

以下是向 Claude Code 提问的示例。你可以用自己的话提问，由助手选择调用哪个工具。输出仅为示例，你看到的会是自己的数据。

作业跟进

> 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_simulate_cumulative_gpa

Şu anki GANO:      2.08
Dönem tahmini:     3.00
Dönem sonu GANO:   2.74

Tekrar aldığın 2 ders eski notun
yerine sayıldı, 1 ders yeni eklendi.

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

更多灵感：

  • “总结 EEF 211E 课程文件中的最新 PDF。”
  • “我的导师是谁？实习情况如何？”
  • “下载我的成绩单。”
  • “BBB 楼现在有空教室吗？”
  • “如果我通过 BLG 223E，哪些课程就可以选了？”
  • “我还差几门课才能毕业？下学期应该选哪些课？”
  • “图书馆有《Introduction to Algorithms》吗？”
  • “列出我最近未读的邮件，并总结附件中的 PDF。”

助手的 / 菜单中还提供了现成的工作流：weekly_briefing（每周摘要）、plan_next_term（规划下学期）、registration_week（选课周检查）、check_course_eligibility、research_course 和 gpa_scenario。

常见问题

我的密码会发送到哪里？

不会发送到任何地方。程序在你的电脑上运行，只会像浏览器一样将密码发送到 ITU 自己的登录页面。中间没有我们或其他人的服务器。代码是开源的，你可以自行查看。

这是 ITU 的官方应用吗？

不是。这是由学生编写的开源项目，与 ITU 没有官方关联。请仅使用自己的账号。

它会修改我账号中的内容吗？

几乎所有操作都只读取数据。只有两个例外，而且都必须得到你的明确同意才会执行：

  • 上传作业。 它会先告诉你要把什么上传到哪里，得到你的确认后才会上传。
  • 保存选课草稿。 默认关闭。即使你启用了此功能，如果草稿中有课程将被删除，它也会停止并询问你。

对于这两种操作，如果你的助手支持，程序都会在提交前直接弹出确认窗口，告诉你将写入哪些文件、哪项作业、哪些 CRN，以及哪些课程将从草稿中移除。助手不能通过自行说“我确认”来绕过此窗口。如果你不确认，就不会提交任何内容。

它不会帮你注册课程、退课或发送邮件。

我可以相信它给出的回答吗？

它会直接从 ITU 系统获取数据，不会编造内容。不过，OBS 有时会根据账号返回不同的信息。如果缺少数据，工具会明确告知。在选课、毕业和成绩等重要事项上，始终以 OBS 自己的页面为准。

它支持哪些助手？

任何支持 MCP 的客户端：Claude Code、Claude Desktop、Cursor、Codex 等。对于 ChatGPT 或 Claude.ai 等网页界面，需要安装远程服务，说明见 docs/advanced.md。

有空位时能通知我吗？

部分可以。你可以将已满额班级的 CRN 添加到监视列表（watch_course_sections），之后询问“我关注的班级有空位了吗”，它会告诉你从上次检查以来发生了哪些变化。此操作无需登录。

不过，程序不会在后台运行，也不会自动发送通知。只有在你询问时才会读取名额。如果你想定期跟踪，需要在助手中设置一个定时任务，每隔几分钟询问一次。

工具数量太多，可以减少吗？

可以。工具分为不同组，每个工具的说明都会在对话开始时加载到助手中。关闭你不用的组后，助手就更容易选对工具。

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

工具组：core、ninova、files、obs、registration、portal、planning、public、campus、library、moodle、archive、mail。如果两项都不填写，则所有工具组都会保持开启。运行 itu-mcp --list-toolsets 可查看每个组包含的工具。

需要付费吗？

不需要。本项目采用 MIT 许可证，完全免费。只有在你使用的助手本身收费时，才需要支付相应费用。

工作原理

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

助手收到问题后，会调用 İTÜ MCP 中合适的工具。工具会访问相关的 ITU 系统，并以规整的格式返回答案，然后由助手向你说明。Ninova 和 OBS 使用相同的 ITU 登录信息。不需要密码的工具完全不会使用你的密码。

显示所有工具
Ninova
giriş gerekir		OBS ve Portal
giriş gerekir		Herkese açık
giriş gerekmez		Planlama ve kütüphane
karma		Arşiv
giriş gerekmez
auth_status · list_courses
get_course_* · sync_all_courses
get_upcoming_deadlines · search_content
export_table · read_resource_text · submit_assignment 		obs_auth_status · obs_get_profile
obs_list_registered_courses
obs_get_registration_draft · obs_save_registration_draft
obs_get_elective_group · obs_validate_registration_plan
obs_get_course_grades · obs_get_attendance
obs_get_advisor · obs_download_transcript
get_cafeteria_menu · obs_get_notifications
obs_get_help_tickets · get_help_ticket 		get_public_course_schedule · get_public_exam_schedule
obs_get_grade_distribution
search_itu_directory · search_campus_locations
get_shuttle_schedule · get_sports_facility_hours
get_itu_announcements · get_academic_calendar
watch_course_sections · check_watched_course_sections
export_course_schedule_ics · export_exam_schedule_ics 		obs_calculate_gpa · obs_simulate_cumulative_gpa · calculate_target_gpa
estimate_relative_grade · check_course_conflicts
find_open_course_sections · find_empty_classrooms
build_degree_plan · library_*
moodle_* · pool_*
search_articles · proquest_search 		archive_who_taught · archive_course_history
archive_fill_rate · archive_term_sections
archive_search_courses · plan_remaining_courses
archive_grade_distribution · archive_course_catalog
archive_course_unlocks · archive_search_sections
archive_exam_schedule · archive_status
İTÜ Mail (salt okunur): mail_status · mail_list_inbox · mail_get_message · mail_get_attachment

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.

Ayarlar (isteğe bağlı)

Ç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_TRACKING_MAX_AGE_SECONDS=43200  # teslim kaydı bu süreden eskiyse yeniden oku (varsayılan 12 saat)
NINOVA_MAIL_USERNAME=...            # mail için ayrı kullanıcı adı
NINOVA_MAIL_PASSWORD=...            # mail için ayrı şifre

.env 文件只会在启动服务的文件夹中查找，不会检查上级文件夹。若要使用其他文件，请将完整路径写入 NINOVA_ENV_FILE 变量。该文件夹中的 .env 可以提供用户名和密码等值，但不能更改地址、服务器、文件夹和写入权限等安全相关设置。请在助手的 env 块中，或在 NINOVA_ENV_FILE 指向的文件中设置这些内容。

完整列表见 .env.example 文件和 docs/advanced.md。有关库目录和代理设置，请参阅 docs/library-catalog.md。

安全

应该做不要做
仅使用你自己的 İTÜ 账户不要与任何人分享你的 .env 文件或密码
上传作业前查看预览不要告诉助手“未经询问就上传”
将公告和邮件内容视为数据不要允许助手遵循公告中的“执行此操作”之类的指令
将下载的文件保存在 ~/.ninova_state/downloads 下；如果需要其他文件夹，请通过 NINOVA_EXTRA_DOWNLOAD_DIRS 自行指定不要允许助手将文件保存到任意文件夹，也不要允许它读取你电脑上的任何文件
如果要设置远程服务，请配置较长且随机的 NINOVA_REMOTE_API_KEY 和 NINOVA_ALLOWED_HOSTS不要通过 NINOVA_REMOTE_ALLOW_UNAUTHENTICATED=1 让服务在没有密钥的情况下暴露到互联网

你需要了解的限制：

  • 接受地址的工具（read_page、download_resource 等）只接受 ninova.itu.edu.tr 地址。OBS、Portal 和帮助请求有各自的专用工具。
  • OBS 个人资料工具会隐藏 TCKN 和电话号码，帮助请求工具会隐藏人名。即使助手提出请求，只有在你设置了 NINOVA_ALLOW_SENSITIVE_OUTPUT=1 后，这些信息才会显示。
  • İTÜ Mail 工具只会通过 993 端口连接到 imap.itu.edu.tr 服务器。
  • 如果远程 HTTP 服务（itu-mcp-remote）绑定到 127.0.0.1 以外的地址（包括 Docker 镜像），则必须提供 NINOVA_REMOTE_API_KEY 和 NINOVA_ALLOWED_HOSTS 或 NINOVA_PUBLIC_BASE_URL，否则服务无法运行，会显示缺少的变量并退出。如果在本地未提供密钥，每次启动时都会生成一个随机密钥，并在屏幕上显示一次。

详情请参阅：docs/security.md 和 docs/advanced.md。

隐私政策（Privacy Policy）

İTÜ MCP 在你的电脑上运行。该项目没有服务器、账户或数据库。

  • 收集的数据： 无。项目开发者不会收到任何数据，也不会进行使用情况统计（遥测）。
  • 使用和存储： İTÜ 用户名和密码只会从你提供的环境变量中读取，并且只会发送到 İTÜ 的登录页面。会话 Cookie、跟踪记录和你下载的文件都保存在你电脑上的 ~/.ninova_state 文件夹中。
  • 与第三方共享： 工具读取的数据会作为回复传递给你使用的 AI 助手（Claude、ChatGPT 等）；这些数据如何处理取决于助手提供方的政策。服务只会向 İTÜ 自有网站和两个公开数据源发送请求：课程档案（itu-ders.com）以及用于比较先修课程的社区数据集（raw.githubusercontent.com/itu-helper）。不会向这两个数据源发送任何与你账户相关的信息，只会查询课程代码。
  • 保留期限： 本地文件会一直保留，直到你将其删除。删除 ~/.ninova_state 文件夹即可移除所有内容。
  • 联系方式： 可通过 GitHub 提交问题，或针对安全问题提交私密报告。

简而言之（英语）：服务在本地运行，不收集任何信息，只会将你的 İTÜ 凭据发送到 İTÜ 登录页面，仅在你自己的电脑上的 ~/.ninova_state 中存储会话 Cookie 和下载内容，并且不进行遥测。工具结果会传递给你使用的 AI 助手。

开发

欢迎贡献。如果你发现了错误或有想法，请创建问题。提交代码前，请先阅读贡献指南。

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/
来源链接
安装docs/installation.md
所有工具和高级用法docs/advanced.md
安全docs/security.md
贡献指南CONTRIBUTING.md
更新日志CHANGELOG.md

致谢

本项目基于 Hikmet Gultekin 编写的原始项目 ninova-mcp 构建。它是首个开源、使用凭据的 İTÜ Ninova MCP 服务。

tzi4 贡献了只读 İTÜ Mail 工具、选课规划和成绩分布工具、帮助请求详情，以及 OBS 端的许多修复。感谢。

许可证

MIT。与伊斯坦布尔技术大学没有官方关联。


由 yatuk 创建 · GitHub

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。