af4464decb
Schulcloud says what was uploaded and WebUntis says what was scheduled. Neither says what was *taught* — which point the teacher laboured, which example landed, what "will definitely come up". That lives in two places this server could not reach: the notes the user takes in the lesson, and WebUntis' class register. Notes are a directory of Markdown files (NOTES_DIR), not a table. They have to be writable from a phone in a classroom, readable when Postgres is down, and outlive this project, and files are the only shape that is all three — so the files are the truth and the index is a view of them, the same split as file_texts and the mirror. list_notes and get_note read disk, so they answer before the first crawl; search, what_changed and all three German prompts read them alongside the Schulcloud material. add_note writes one, and is the only thing in this server that writes anything. That is not a hole in the read-only invariant but a different store: it is bounded to NOTES_DIR by the same safeComponent/resolveWithin pair that stops a hostile Schulcloud filename escaping the mirror, so a note titled ../../.ssh/authorized_keys becomes a filename. Schulcloud and WebUntis stay GET-only and allowlisted respectively. NOTES_READONLY refuses writes outright. Appending targets the *lesson*, not the title: "halt das auch noch fest" mid-lesson carries a new title, and deriving the path from it would start a second note every time, which is the one thing append exists to prevent. Notes.app has no export — its bodies are compressed protobuf and the iCloud copy is encrypted — so scripting the app is not the clumsy route to the notes but the only one. scripts/export-apple-notes.js reads them through AppleScript into one JSON object per line, and `schulcloud note import` converts the HTML to Markdown, takes the Notes folder as the subject and the *creation* date as the lesson's date. Attachments cannot come across; a note that was a photo of the board imports as a line saying so, because importing it empty would hide the loss. The class register needed one API property to become cheap: getLessonTopic2017 answers per *series*, not per period, so a term is reconstructed by asking about the latest period of each lesson series and merging back by id — a few dozen calls for a school year rather than one per lesson. untis_lesson_topics now takes a subject as well as a period id, and UNTIS_HISTORY_DAYS of register goes into the index under a kind of its own, so "what did we actually do before the test" is searchable. Sharing the snapshot rather than duplicating it caught one thing on the way: the search tool's live path had to learn notes too, or fresh=true would have quietly disagreed with the index. 305 tests; 88/89 smoke against the local instance, the one failure being the H5P service that instance does not run. The live smoke could not be retaken: that session has lapsed and needs a fresh jwt cookie. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
13 KiB
schulcloud-mcp
Read-only access to a Schulcloud account — courses, boards, lessons, tasks and files — plus the timetable from WebUntis and the notes you take in class, for Claude, via MCP, and for you, via a CLI that mirrors your coursework to disk.
Both are front ends over one core library and one live Schulcloud session, kept alive on a Pi.
Built and verified against schulcloud-thueringen.de with a live student
account. Everything in docs/API.md was confirmed against the running
instance, not inferred from the upstream source.
What Claude can do with it
"What do I have due this week?" "Find the material about Verschlüsselung and explain the Caesar cipher worksheet." "Summarise the routing lesson from the LF10 course." "What do I have tomorrow, and has anything been cancelled?" "Quiz me on the DIN 5008 exercise from the DK room." "What did we actually cover in Deutsch before the test — and what did I write down?"
Thirty-one tools. Everything that touches Schulcloud and WebUntis is read-only;
add_note writes a file in your own notes directory and nowhere else.
whoami |
account, school, roles — also a connectivity check |
list_courses |
all courses, with ids |
get_dashboard |
the tiles as pinned on the web dashboard |
get_course |
one course's boards, topics and tasks |
get_board |
a column board in full: columns, cards, text, links, files |
get_lesson |
a topic's text sections, materials, files and tasks |
list_tasks |
homework across all courses, by due date |
get_task |
one task: description, due date, attachments, and your submission |
list_submissions |
what you handed in, and what is still ungraded |
list_files |
files attached to a board element, topic, task or submission |
download_file |
fetch such an attachment and extract its text, or view an image |
fs_list |
list a folder of the file manager — Persönliche, Kurs-, Team-, Geteilte Dateien |
fs_tree |
everything below a file-manager folder, as a tree |
fs_find |
find file-manager files and folders by name |
fs_read |
read a file-manager file, extracted like download_file |
search |
keyword search across everything — including the text inside PDFs and Office files |
refresh_index |
re-read Schulcloud now, per course or in full |
what_changed |
what appeared, changed or vanished since a date |
index_status |
how fresh the index is |
list_rooms |
rooms ("Räume"), which are a separate space from courses |
get_room |
one room: its boards, members and what you may do there |
list_classes |
classes ("Klassen") with their teachers, and group membership |
list_news |
school and course announcements |
get_h5p |
an H5P exercise in full: every question, option and correct answer |
api_get |
GET-only escape hatch for uncovered API surface |
untis_timetable |
the school day from WebUntis: lessons, Entfall, Vertretung, room changes, period notes |
untis_homework |
homework from WebUntis' class register — a separate list from Schulcloud's tasks |
list_notes |
your own lesson notes — what you wrote down, by subject or date |
get_note |
one of your notes in full |
add_note |
write a note down during or after a lesson |
untis_lesson_topics |
what previous lessons of a subject actually covered ("Unterrichtsinhalt") |
download_file extracts text from PDF, DOCX, XLSX, PPTX and OpenDocument
files and returns images inline for Claude to look at. Image-only PDFs —
scans with no text layer, which are common in this account — are reported as
such rather than as an empty result.
Attach a course instead of asking for it. Every course and room is also an
MCP resource (schulcloud://courses/<id>, schulcloud://rooms/<id>) holding
the same overview get_course and get_room return. In Claude Code, type @
and part of the course name.
Your own notes are the third source. Schulcloud has the material and
WebUntis has the schedule; neither has what the teacher actually stressed. Point
NOTES_DIR at a directory of Markdown files and search, what_changed and
all three prompts read it alongside everything else — including a migration path
out of Apple Notes. See docs/NOTES.md.
Three ready-made prompts, in German because the school is:
zusammenfassung kurs [fokus] |
summarise a course or room: topics, tasks, key material, each with its source |
pruefungsvorbereitung kurs [thema] [datum] |
prepare for an exam: scope, explanations, practice questions, a study plan |
tagesvorbereitung [tag] |
prepare a school day: the lessons from WebUntis, what is new in those courses, what is due |
In Claude Code they run as /mcp__schulcloud__zusammenfassung Mathe_10b, or
/mcp__schulcloud__tagesvorbereitung morgen the evening before.
Claude Code splits arguments on spaces and drops extra words, so join words
with _ (Lineare_Funktionen) and skip an optional argument with -. kurs
is any unambiguous part of a course or room name, or its id; tag takes
heute, morgen, übermorgen, 21.09.2026 or 2026-09-21.
The CLI
schulcloud login --server https://mcp.example.org --token <token>
schulcloud sync --dry-run # see what would be mirrored
schulcloud sync # mirror coursework to ~/Schulcloud
schulcloud refresh --course <id>
schulcloud fs tree /courses # browse the file manager ("Dateien")
schulcloud fs get "/courses/<course>/<folder>"
schulcloud note ls --subject Deutsch
pbpaste | schulcloud note add --title Subnetting --subject LF07
schulcloud token set # the monthly chore: hand the Pi a fresh Schulcloud token
It talks only to the Pi and holds no Schulcloud credential — see
docs/CLI.md. A fresh token can also be pasted into the server's
/token page; either way the server checks it with Schulcloud and swaps it in
without a restart.
Quick start
cp .env.example .env # fill in TSC_URL and TSC_JWT_COOKIE
npm install
npm run build
npm run probe # verifies the token and API against the live instance
To try it on your own machine — Docker stack, Claude Code, and the CLI — follow docs/LOCAL.md. To put it on a Pi behind Caddy and a VPS, and connect claude.ai, follow docs/PI.md; docs/DEPLOYMENT.md explains the pieces.
Getting TSC_JWT_COOKIE takes four clicks in DevTools and then lasts 30 days —
provided you close the Schulportal window afterwards. See
docs/AUTH.md; that caveat is not optional.
Design decisions
Bearer token plus a keepalive. The instance's jwt cookie works verbatim
as Authorization: Bearer — no cookie jar, no connect.sid. Its exp claim
(30 days) is only a ceiling: the real limit is a 2-hour server-side session TTL
that any request slides, so the server calls refresh-session every 30 minutes
(the one non-GET request here, and not exposed as a tool).
The sharp edge is subtler and cost two endurance tests to find: the cookie you copy is the browser's own session token, so a Schulportal tab left open will auto-logout after ~2 hours and revoke this server's token with it. Copy the token in a private window and close it. See docs/AUTH.md.
The timetable comes from somewhere else. Schulcloud holds the material for
a lesson but not the lesson: this school's course times are empty and it
publishes its schedule in WebUntis. So the server reads that too, through
the API the Untis Mobile app uses — which authenticates with a key from Profil →
Freigaben and a time-based code per request, meaning no password, no session to
hold open and nothing that expires monthly. The two systems answer different
halves of the same question, and the German tagesvorbereitung prompt is where
they meet: which lessons happen today, what changed in their courses, what is
due. That key can write (the app may report an absence), so this side is kept
read-only by an allowlist of five read methods rather than by "GET only". Unset
UNTIS_* and none of it exists — the tools are not even offered. See
docs/AUTH.md.
A quiz is one request, not a wizard. Schulcloud has no quiz of its own, so
an exercise is an H5P element and the board hands over nothing but a content
id. The player then shows one question at a time, which makes a quiz look like
something to step through or scrape — it isn't: the endpoint the player loads
returns the whole exercise, every option and every solution. So get_h5p
prints all of it, get_board names it with its question count, and search
reaches the question text like any other material.
claude.ai gets a token of its own. Its connector stores a request header,
so MCP_CONNECTOR_TOKEN opens /mcp and nothing else — it is refused on
/api, which can replace the Schulcloud token — and rotates without touching
Claude Code or the CLI, which keep MCP_AUTH_TOKEN. A client that cannot send
headers can use a secret path instead (MCP_PATH_SECRET). See
docs/DEPLOYMENT.md.
Read-only by construction. Every method on the API client is a GET,
including api_get. The endpoint is internet-facing by necessity (Claude's
connectors call it from Anthropic's cloud), so the fact that a leaked token
cannot be used to act as the user is the main safety property. Adding one
write tool would forfeit it.
An index, with an honest bypass. Postgres holds crawl generations and a
german + pg_trgm full-text index over extracted file text, so search covers
the inside of PDFs rather than just their names. Every result states how fresh
the index is, and fresh=true bypasses it for a live read — an agent should
never be quietly misled by stale data. Without DATABASE_URL the server still
works: search falls back to crawling live.
Generations, not timestamps. Sync cursors and change detection compare crawl
generations by identity. Measured: the course-board endpoint returns request
time as updatedAt, so a timestamp cursor would report everything as changed
on every crawl — and could never detect deletions.
Assembled, not raw. get_board makes three kinds of upstream call and
stitches the results — board skeleton, card bodies, and a files-storage lookup
per file element — because a model asking "what's on this board" wants the
answer, not a traversal plan. Output is Markdown with ids preserved for
follow-up calls, not raw JSON.
Possible extensions — full-text search over file contents, a cache with a bypass, "what's new since…" — are sketched with their trade-offs in docs/ROADMAP.md. None are built.
Layout
src/
core/ client, types, board assembly, crawler, extraction, paths,
WebUntis and its class register, your own notes
store/ Postgres: crawl generations, diffs, full-text search
indexer/ crawl → persist → mirror bytes → extract text → index
mcp/ MCP server, tools, resources and prompts
http/ express app, bearer auth, /api for the CLI
cli/ CLI config, API client, sync engine
bin/ http, stdio and cli entry points
docs/ API findings, auth, deployment, CLI, notes, roadmap
deploy/ Caddyfile snippet, the Pi's compose file
scripts/ probe, smoke, session diagnostics
vendor/ upstream clones, git-ignored, for reference only
core/ knows nothing about MCP, HTTP or the CLI: it holds the Schulcloud client,
the traversal every feature needs, document extraction, the WebUntis client with
its one-time codes, and the path sanitisation that both the server's mirror and
the CLI's sync depend on.
Development
npm run dev # watch mode, runs src/ directly
npm test # unit tests, no network
npm run probe # check assumptions against the live instance
npm run smoke # full end-to-end: real server, real client, real data
npm run session-diagnose # instrument what actually ends the session (~2.5h)
npm run keepalive-status # is the deployed container holding its session?
npm run publish-image # build amd64 + arm64 and push to registry.mc02.dev — the Pi only pulls
npm run typecheck
npm run smoke starts the HTTP server, connects a real MCP client over
Streamable HTTP and exercises every tool against the live account — 91 checks (93 with the index, 9 fewer without a WebUntis key)
covering the auth gate, the connector token and the secret path, the protocol handshake, every content chain, file
extraction, resources and prompts, token replacement, api_get's guard rails and error handling.
Upstream
Reference clones live in vendor/ (git-ignored):
git clone --depth 1 --filter=blob:none https://github.com/hpi-schul-cloud/schulcloud-server.git vendor/schulcloud-server
git clone --depth 1 --filter=blob:none https://github.com/hpi-schul-cloud/file-storage.git vendor/file-storage
git clone --depth 1 --filter=blob:none https://github.com/hpi-schul-cloud/nuxt-client.git vendor/nuxt-client
Most of that organisation's ~100 repositories are archived or superseded; those
three are the live ones that matter. The instance's own OpenAPI documents
(/api/v3/docs-json, /api/v3/file/docs-json) are more authoritative than any
of them — see docs/API.md.