itmo-mcp

MCP-сервер для сервисов Университета ИТМО: my.itmo.ru и БАРС, а также ITMO.Widgets (отзывы о преподавателях, ссылки предметов, очереди на физкультуру). Подключите его к Claude, Codex, Cursor или другому MCP-клиенту и спрашивайте обычным языком: "какие пары завтра?", "сколько баллов по матану в БАРС?", "куда записаться на волейбол на этой неделе?", "что пишут про преподавателя по матану?".

По умолчанию сервер только читает данные. Запись на физкультуру, бронирование аудиторий и подачу заявок можно включить отдельно (см. "Изменение данных"): каждое действие сначала показывается и выполняется только после вашего подтверждения.

Неофициальный проект. Не связан с Университетом ИТМО. API сервисов может измениться без предупреждения.

Быстрая настройка через агента

Отправьте своему агенту (Claude Code, Codex, Cursor):

Настрой мне MCP-сервер itmo-mcp по README https://github.com/alllexey-dev/itmo-mcp

Что умеет

Инструмент	Что возвращает
`itmo_get_profile`	Ваш профиль: ИСУ, ФИО, факультет, группа, курс
`itmo_get_schedule`	Расписание пар за период (по умолчанию 7 дней)
`itmo_get_grades`	Зачётка за семестр: баллы, оценки, тип контроля
`itmo_get_grade_details`	Разбивка баллов по одной дисциплине зачётки
`itmo_get_study_plan`	Дисциплины учебного плана за семестр: ЗЕТ, часы, кафедра
`bars_get_scores`	Баллы БАРС текущего семестра по контрольным точкам
`itmo_get_sport_status`	Физкультура: баллы, секции, ближайшие занятия, долги
`itmo_get_sport_points_history`	История начисления баллов по физкультуре
`itmo_get_sport_schedule`	Занятия по физкультуре со свободными местами
`itmo_get_sport_filters`	Виды спорта, корпуса и семестры для фильтров
`itmo_get_sport_competitions`	Спортивные соревнования
`itmo_get_scholarship`	Стипендия и выплаты: суммы по категориям и история
`itmo_get_dormitory`	Общежитие: статус, договор, баланс и график оплаты
`itmo_get_room_bookings`	Ваши брони аудиторий и коворкингов
`itmo_get_queue_appointments`	Записи в электронную очередь
`itmo_get_requests`	Ваши заявки и справки
`itmo_get_election_status`	Сроки выбора дисциплин
`itmo_search_people`, `itmo_get_person`	Поиск студентов и сотрудников, профиль по ИСУ
`itmo_booking_places`, `itmo_booking_search_rooms`	Где можно забронировать аудиторию или коворкинг
`itmo_booking_availability`	Свободное время комнат на дату (чужие брони только как "занято")
`itmo_requests_catalog`, `itmo_request_form`	Какие справки и заявки можно подать, поля формы
`itmo_get_request_details`	Статус и поля поданной заявки
`widgets_get_teacher_reviews`	Отзывы о преподавателе из ITMO.Widgets и сводка по ним (доступ «Отзывы о преподавателях»)
`widgets_get_subject_links`	Ссылки и чаты предмета от однокурсников (доступ «Ссылки предметов»)
`widgets_get_sport_queue`	Ваши очереди на физкультуру в ITMO.Widgets (доступ «Очереди на физкультуру»)

Инструменты widgets_* работают после подключения через приложение ITMO.Widgets (см. "Вход в ИТМО"). Если нужного доступа нет, инструмент скажет, какой переключатель включить в приложении: Профиль -> Устройства.

Изменение данных

Включается переменной ITMO_MCP_ENABLE_WRITES=true и добавляет инструменты:

Инструмент	Что делает
`itmo_sport_signup_preview`, `itmo_sport_cancel_preview`	Запись на занятие физкультурой или в секцию на семестр, отписка
`itmo_sport_competition_preview`	Регистрация на соревнование или отказ от участия
`itmo_booking_create_preview`, `itmo_booking_cancel_preview`	Бронь аудитории или коворкинга, отмена своей брони
`itmo_request_submit_preview`, `itmo_request_cancel_preview`	Подача заявки (например, справки с места учёбы), отмена
`widgets_sport_queue_join_preview`, `widgets_sport_queue_leave_preview`	Очередь ITMO.Widgets на свободное место или автозапись, выход из очереди (записывает телефон)
`itmo_confirm_action`	Выполняет подготовленное действие

Любое изменение идёт в два шага. Инструмент *_preview ничего не меняет: он перечитывает данные, проверяет правила (свободные места, попытки, пересечения, обязательные поля) и возвращает описание действия и одноразовый confirmation_token на 10 минут. Агент показывает его вам, и только после вашего согласия вызывает itmo_confirm_action. Клиенты MCP дополнительно спрашивают разрешение на этот вызов, потому что он помечен как изменяющий данные.

Чего сервер не делает никогда: не подписывает документы электронной подписью, не платит, не трогает медданные и не подаёт заявления, меняющие статус студента (отчисление, академический отпуск, перевод).

Вход в ИТМО

Через приложение ITMO.Widgets (рекомендуется)

npx -y itmo-mcp setup

setup показывает QR-код, а потом предлагает добавить сервер в Claude Code, Codex и Cursor. Только подключить без клиентов: npx -y itmo-mcp pair.

В приложении ITMO.Widgets: Профиль -> Устройства -> «Подключить устройство», отсканируйте QR или вставьте ссылку из терминала. Ссылка действует 2 минуты, не пересылайте её.
Сверьте код проверки в терминале и на телефоне, выберите доступы и войдите в ITMO.ID в окне приложения.
Телефон передаёт серверу зашифрованный вход: отдельную сессию ITMO.ID только для этого сервера (на id.itmo.ru/activity это отдельная строка) и токен ITMO.Widgets. Ни пароль, ни cookie телефона сервер не получает.

Команда	Что делает
`itmo-mcp pair`	Подключение по QR-коду (`--name`, `--scopes reviews:read,links:read,sport:queue`)
`itmo-mcp setup`	`pair`, затем добавляет сервер в Claude Code, Codex и Cursor (спрашивает про каждый)
`itmo-mcp status`	Доступы, состояние входа в ИТМО и дата его окончания, доступность ITMO.Widgets
`itmo-mcp renew`	Новый вход в ИТМО для того же подключения (QR-код ещё раз)
`itmo-mcp unpair`	Завершает свою сессию ITMO.ID, отключает сервер в ITMO.Widgets и стирает его данные

Сессия ITMO.ID живёт не больше 90 дней с входа. Когда ИТМО её закрывает, инструменты my.itmo.ru отвечают, что нужен itmo-mcp renew, а приложение видит это в «Устройствах».
Если отключить сервер в приложении, при следующем запросе он сам завершит свою сессию ITMO.ID и сотрёт данные.
Через подключение доступен только my.itmo.ru. Инструменты БАРС работают только с ITMO_KEYCLOAK_IDENTITY ниже, на ваш риск: эта cookie даёт полный доступ к аккаунту ITMO.ID, поэтому приложение её не передаёт.
Сервер показывает только инструменты, которые сейчас могут работать: bars_* - пока есть ITMO_KEYCLOAK_IDENTITY, которую ITMO.ID принимает, widgets_* - после подключения к приложению.

Без приложения (переменные окружения)

Переменная	Доступ	Комментарий
`ITMO_KEYCLOAK_IDENTITY`	my.itmo.ru и БАРС	Cookie живёт около 90 дней. Это весь аккаунт: храните как пароль
`ITMO_REFRESH_TOKEN`	только my.itmo.ru	Токен живёт 30 дней и обновляется сам

После подключения через приложение my.itmo.ru работает только через свою сессию, а ITMO_KEYCLOAK_IDENTITY нужна лишь для БАРС. Вход по логину и паролю (ITMO_USERNAME, ITMO_PASSWORD) убран в 0.3.0.

Как получить KEYCLOAK_IDENTITY: войдите на my.itmo.ru, откройте DevTools (F12) -> Application -> Cookies -> https://id.itmo.ru и скопируйте значение KEYCLOAK_IDENTITY.

ITMO.ID меняет токены при каждом входе. Сервер сохраняет свежие значения и подключение в ~/.config/itmo-mcp/state.json (права 600), поэтому после первого входа переменные можно не обновлять. Папку можно поменять через ITMO_MCP_STATE_DIR.

Переменная	Назначение
`ITMO_MCP_ENABLE_WRITES`	`true` разрешает запись, бронь, заявки и очереди (см. "Изменение данных")
`ITMO_BROWSER_UA`	По умолчанию `true`: свои входы в ITMO.ID выглядят как Chrome. `false`: честная подпись `ITMO Widgets MCP bot`
`ITMO_WIDGETS_URL`	Сервер ITMO.Widgets, по умолчанию `https://widgets.alllexey.dev`

Подключение

Нужен Node.js 20 или новее.

Claude Desktop

Сначала подключите сервер (npx -y itmo-mcp pair), затем Settings -> Developer -> Edit Config, добавьте в claude_desktop_config.json (переменные окружения из "Вход в ИТМО" кладутся в "env"):

{
  "mcpServers": {
    "itmo": {
      "command": "npx",
      "args": ["-y", "itmo-mcp"]
    }
  }
}

Claude Code

claude mcp add --scope user itmo -- npx -y itmo-mcp

Codex

codex mcp add itmo -- npx -y itmo-mcp

Или вручную в ~/.codex/config.toml. Первый запуск npx скачивает пакет, поэтому таймаут старта увеличен:

[mcp_servers.itmo]
command = "npx"
args = ["-y", "itmo-mcp"]
startup_timeout_sec = 60

Cursor, VS Code и другие клиенты

Используйте ту же команду (npx -y itmo-mcp) и те же переменные окружения в настройках MCP вашего клиента.

Docker вместо Node.js

Подключение сохраняется в томе itmo-mcp:

docker run -it --rm -v itmo-mcp:/state ghcr.io/alllexey-dev/itmo-mcp:v0.3.1 pair

{
  "mcpServers": {
    "itmo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "itmo-mcp:/state", "ghcr.io/alllexey-dev/itmo-mcp:v0.3.1", "--stdio"]
    }
  }
}

Свой сервер (HTTP)

Сервер умеет Streamable HTTP: POST /mcp, health check на GET /healthz. Подключите его так же, как в Docker выше (... -v itmo-mcp:/state ... pair), затем:

docker run -d --name itmo-mcp -p 8080:8080 \
  -e ITMO_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -e ITMO_MCP_HTTP_ALLOWED_HOSTS=mcp.example.com \
  -v itmo-mcp:/state \
  ghcr.io/alllexey-dev/itmo-mcp:v0.3.1

Переменная	Назначение
`ITMO_MCP_HTTP_TOKEN`	Клиент должен прислать `Authorization: Bearer <токен>`
`ITMO_MCP_HTTP_ALLOWED_HOSTS`	Допустимые значения заголовка `Host`, через запятую (защита от DNS rebinding)

Один сервер обслуживает один аккаунт ИТМО. Не открывайте его в интернет без токена или прокси с авторизацией: любой, кто до него достучится, увидит ваши данные. Подключение из Claude Code:

claude mcp add --transport http itmo https://mcp.example.com/mcp --header "Authorization: Bearer <токен>"

Из Codex (токен берётся из переменной окружения ITMO_MCP_TOKEN):

codex mcp add itmo --url https://mcp.example.com/mcp --bearer-token-env ITMO_MCP_TOKEN

Приватность

Сервер обращается напрямую к id.itmo.ru, my.itmo.ru и bars.itmo.ru, а после подключения ещё к ITMO.Widgets (widgets.alllexey.dev): за отзывами, ссылками и очередями и чтобы сообщить, работает ли его вход в ИТМО. Токены ИТМО к ITMO.Widgets не уходят.
Ответы инструментов попадают в контекст модели и, значит, к провайдеру LLM, которым вы пользуетесь.
Токены и cookie не попадают в ответы инструментов и в логи.

OpenAPI и клиент

В openapi/ лежат описания API (OpenAPI 3.1), восстановленные по веб-клиентам и проверенные на живых ответах:

openapi/my-itmo.yaml: расписание, зачётка, учебный план, физкультура, финансы, общежитие и другое;
openapi/bars.yaml: БАРС.

По ним сгенерирован типизированный клиент на openapi-fetch, который можно использовать как библиотеку:

import { createToolDeps, loadConfig, result } from "itmo-mcp";

const { my } = createToolDeps(loadConfig());
const requests = await result("getMyRequests", my.GET("/api/requests/my"));

Исследование API ИТМО

В папке research/ собрана документация по студенческим сервисам ИТМО (my.itmo.ru, БАРС, бэкенды мобильного приложения и другие): откуда данные, как устроена авторизация, карта хостов и отдельный документ на каждый сервис с таблицей ручек и статусом проверки. Там же лежат исследовательские OpenAPI-спецификации для ручек, которых нет в контракте выше. Это справочный материал, а не часть сервера.

Разработка

npm install
npm test             # юнит-тесты и проверка спек на фикстурах
npm run lint:spec    # линтер OpenAPI
npm run gen          # перегенерировать src/generated после правки openapi/
npm run verify:live  # сверить спеки с живыми ответами (нужны ITMO_* переменные)
npm run build

verify:live выводит только названия операций, HTTP-статусы и пути ошибок схемы, без самих данных. Новые фикстуры добавляйте только после scripts/sanitize-fixture.ts, он убирает персональные данные.

Изменения

См. CHANGELOG.md.

Лицензия

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
openapi		openapi
research		research
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
redocly.yaml		redocly.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

itmo-mcp

Быстрая настройка через агента

Что умеет

Изменение данных

Вход в ИТМО

Через приложение ITMO.Widgets (рекомендуется)

Без приложения (переменные окружения)

Подключение

Claude Desktop

Claude Code

Codex

Cursor, VS Code и другие клиенты

Docker вместо Node.js

Свой сервер (HTTP)

Приватность

OpenAPI и клиент

Исследование API ИТМО

Разработка

Изменения

Лицензия

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

itmo-mcp

Быстрая настройка через агента

Что умеет

Изменение данных

Вход в ИТМО

Через приложение ITMO.Widgets (рекомендуется)

Без приложения (переменные окружения)

Подключение

Claude Desktop

Claude Code

Codex

Cursor, VS Code и другие клиенты

Docker вместо Node.js

Свой сервер (HTTP)

Приватность

OpenAPI и клиент

Исследование API ИТМО

Разработка

Изменения

Лицензия

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages