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

Related MCP server: MyIIS MCP Server

Что умеет

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

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

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

Любое изменение идёт в два шага. Инструмент *_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.

1. В приложении ITMO.Widgets: Профиль -> Устройства -> «Подключить устройство», отсканируйте QR или вставьте ссылку из терминала. Ссылка действует 2 минуты, не пересылайте её.

2. Сверьте код проверки в терминале и на телефоне, выберите доступы и войдите в ITMO.ID в окне приложения.

3. Телефон передаёт серверу зашифрованный вход: отдельную сессию ITMO.ID только для этого сервера (на id.itmo.ru/activity это отдельная строка) и токен ITMO.Widgets. Ни пароль, ни cookie телефона сервер не получает.

• Сессия 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_* - после подключения к приложению.

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

После подключения через приложение 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.

Подключение

Нужен 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

Один сервер обслуживает один аккаунт ИТМО. Не открывайте его в интернет без токена или прокси с авторизацией: любой, кто до него достучится, увидит ваши данные. Подключение из 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