itslearning-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
itslearning-mcp
A read-only Model Context Protocol server for itslearning, the learning platform used by many schools. It lets AI agents (Claude, or any other MCP client) read a student's tasks, news, course announcements, messages and course files – and redacts personal data before anything leaves the server.
Agent ──MCP──▶ itslearning-mcp ──REST──▶ https://<your-school>.itslearning.com
│
└─ pseudonymises people, strips e-mail/phone/links/tokens,
returns slim, allowlisted results only⚠️ Disclaimer
Unofficial. This project is not affiliated with, endorsed by or supported by itslearning AS. "itslearning" is a trademark of its owner.
It uses the undocumented REST API of the official itslearning mobile app, including that app's public OAuth client ID. The API can change or break at any time without notice.
It is read-only: it cannot submit work, send messages or change anything.
You are responsible for complying with the terms of use of your school and of itslearning, and with data-protection law (e.g. the GDPR) – especially because the data concerns minors and third parties (classmates, teachers). Only use it with an account you are entitled to use.
Pseudonymisation is not anonymisation. Redaction considerably reduces what reaches an AI model, but it cannot catch everything (see Limits). In particular, file and image contents are not redacted – only extracted text is.
Provided "as is", without warranty (see LICENSE).
Related MCP server: Moodle MCP for Students
Features
10 read-only tools: overview, courses, tasks (+ details), news, course announcements, message threads (+ messages), course files and file downloads.
Redaction by default: the account owner becomes
Me, teachersTeacher Müller(orMrs Müller), classmatesStudent-7F3A; names in free text, e-mail addresses, phone numbers, internal links, tokens and encoded data blobs are removed. Labels in English (default) or German.File downloads with text extraction (PDF, DOCX, text) – the extracted text is redacted, too.
Two transports: stdio for local clients, stateless Streamable HTTP with API key for Docker/remote use.
Gentle on the instance: caching, rate limiting, retries with backoff, single login with a persisted, rotating refresh token.
Docker image (non-root, read-only filesystem) published to GHCR.
Leak smoke test against your real account that prints counts only, so you can share its output.
Requirements
An itslearning instance with native login (user name + password on the itslearning login page). Instances that only offer login via a third-party identity provider (Microsoft, Google, Feide, …) are not supported – the server detects this and reports
SSO_NOT_SUPPORTED.A student account. Parent accounts are not supported yet (see roadmap).
Docker, or Bun ≥ 1.4 to run it without Docker.
Check your instance first
A compatibility check tells you whether itslearning-mcp can work with your school's instance – before you set anything up:
# with Docker (nothing to install)
docker run --rm -it ghcr.io/ludoo0/itslearning-mcp bun src/check/cli.ts https://yourschool.itslearning.com
# or from a clone
bun run check https://yourschool.itslearning.comWithout credentials it checks reachability, the login method (native vs. single sign-on only), the REST API and whether the mobile-app login is accepted – the latter with a random, non-existent user name.
Optionally (
--login, or answer the prompt) it also tests your account: login, token refresh, account type, core endpoints, course participants and the file download path. Your credentials are only sent after all public checks passed and only to*.itslearning.com.ITSL_USERNAME/ITSL_PASSWORDfrom the environment are only used ifITSL_BASE_URLmatches the checked URL.--no-loginskips the account part,--jsonprints a machine-readable report.
The output contains only status codes and counts – no names or content – so you can paste it into an issue. Nothing is stored.
Tools
Tool | What it does |
| Starting point: overdue and upcoming tasks, recent news, unread message threads |
| Current (optionally all) courses with |
| Tasks/homework sorted by deadline; filter by course, status, due date, homework, active courses |
| Task details: assignment text, deadline, submission type, attachments ( |
| News feed across all courses or one course, optionally since a date |
| Announcements of a course incl. attached resources and images |
| Message threads with last message and unread status |
| Messages of a thread in chronological order, attachments as |
| Folders and elements of a course (optionally recursive) with |
| Download a file by |
Quick start (Docker)
git clone https://github.com/Ludoo0/itslearning-mcp.git
cd itslearning-mcp
# 1. Secrets (secrets/ is ignored by git and by the Docker build)
cp -r secrets.example secrets
# edit secrets/itsl_username, secrets/itsl_password, secrets/mcp_api_key
# generate an API key, e.g.:
openssl rand -hex 32
# 2. Start (prebuilt image from GHCR)
export ITSL_BASE_URL=https://yourschool.itslearning.com
docker compose pull && docker compose up -d
docker compose ps # should become "healthy"
# …or build the image locally instead
docker compose up -d --buildPowerShell: Copy-Item -Recurse secrets.example secrets and $env:ITSL_BASE_URL = "https://yourschool.itslearning.com". Compose also reads ITSL_BASE_URL from a .env file next to compose.yaml. Pin a version with ITSLEARNING_MCP_VERSION=0.1.0.
The server listens on
http://127.0.0.1:3000/mcp(localhost only). For access from other machines put a TLS reverse proxy in front.Every request needs
Authorization: Bearer <mcp_api_key>.GET /healthzis unauthenticated.Container: Alpine, user
bun(UID 1000), read-only root filesystem except/data(volume) and/tmp, all capabilities dropped.On Linux hosts the secret files must be readable by UID 1000 (
sudo chown 1000:1000 secrets/*).
Connect a client
Claude Code (HTTP):
claude mcp add --transport http itslearning http://127.0.0.1:3000/mcp \
--header "Authorization: Bearer $(cat secrets/mcp_api_key)"Claude Desktop / other stdio clients (claude_desktop_config.json):
{
"mcpServers": {
"itslearning": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT=stdio",
"-e", "ITSL_BASE_URL=https://yourschool.itslearning.com",
"-e", "ITSL_USERNAME=…",
"-e", "ITSL_PASSWORD=…",
"-v", "itsl-data:/data",
"ghcr.io/ludoo0/itslearning-mcp:latest"
]
}
}
}Running locally (without Docker)
bun install
cp .env.example .env # fill in ITSL_BASE_URL, ITSL_USERNAME, ITSL_PASSWORD
bun test
# List the tools (no login needed)
bun run call
# Call tools against your account (Bun loads .env automatically; otherwise you are prompted, password hidden)
bun run call itslearning_overview
bun run call itslearning_list_tasks limit=5
bun run call itslearning_get_task elementId=123
bun run call itslearning_list_course_files courseId=123 recursive=true
bun run call itslearning_download_file fileRef=e_123Use it from Claude Code via stdio:
claude mcp add itslearning \
-e ITSL_BASE_URL=https://yourschool.itslearning.com \
-e ITSL_USERNAME=… -e ITSL_PASSWORD=… \
-e DATA_DIR=/path/to/itslearning-mcp/.data \
-- bun run /path/to/itslearning-mcp/src/server.tsDATA_DIR (default /data, .data in .env.example) holds:
state.json– login state (rotating refresh token; the password is never stored)secret– key for stable pseudonymsteachers.json– teacher directory (see below)files/– file cache (24 h, max. 500 MB)
Configuration
All settings are environment variables. Variables marked (file) also accept <NAME>_FILE pointing to a file (Docker secrets), which takes precedence.
Variable | Default | Description |
| required | Your instance, e.g. |
| required | itslearning user name |
| required | itslearning password |
| mobile app client ID | OAuth client ID |
|
|
|
|
| HTTP bind address |
|
| HTTP port |
| required for | Bearer key for clients, ≥ 32 characters |
| empty | Allowed browser origins (comma-separated); other |
|
| Labels and placeholders: |
| generated | HMAC secret for pseudonyms (≥ 16 characters), stored in |
| empty | Comma-separated words never replaced as a single name (see below) |
|
|
|
|
| Role titles that count as teacher (substring, case-insensitive) |
|
| Maximum download size |
|
| List cache lifetime |
|
| Parallel requests to itslearning |
|
| Minimum spacing between requests |
|
| Persistent state, secret, teacher directory, file cache |
| – | Additionally save downloaded files here (redacted file name) |
|
|
|
Privacy and redaction
How people appear in tool output:
Who |
|
|
Account owner |
|
|
Teacher (salutation set) |
|
|
Teacher (no salutation) |
|
|
Teacher with |
|
|
Classmate |
|
|
Unknown role |
|
|
Placeholders: [email], [phone], [itslearning link], [link removed], [encoded data removed], [name] (ambiguous name), [ID] (de: [E-Mail], [Telefon], [itslearning-Link], [Link entfernt], [kodierte Daten entfernt], [Name]).
How it works:
Tools return allowlisted fields only, never raw API responses. Person IDs and profile/avatar URLs are never emitted.
Pseudonyms are stable (HMAC of the person ID with a local secret), so an agent can tell that two messages come from the same person.
Names in free text (tasks, news, messages, thread titles, file names, extracted file text) are replaced using a dictionary of every person the server knows: participants of recent message threads (loaded at startup), course participants (loaded before course content) and every person in API responses.
E-mail addresses, phone numbers, itslearning links, tokens, ID pairs and URL-encoded data are removed. External links are kept only if their parameters look harmless.
Teacher salutations
Teachers are added automatically to DATA_DIR/teachers.json (last name only – no first names, no IDs):
{ "teachers": [ { "id": "A3F2C1D0", "lastName": "Müller", "salutation": "" } ] }Set salutation (e.g. "Mrs", "Mr", "Frau", "Herr") and the agent sees Mrs Müller; leave it empty for Teacher Müller. Changes apply without restart. The salutation is never guessed. In Docker: docker compose exec itslearning-mcp vi /data/teachers.json.
REDACTION_KEEP_WORDS
A person's last name can also be an ordinary word (e.g. a place adjective in an event title) and would then be replaced everywhere. Words listed in REDACTION_KEEP_WORDS are never replaced as a single name – but then also not where they really refer to that person. Full names are still replaced. Set it via .env/compose, not in the repository.
Limits
Names that never appear in a structured field (e.g. parents, people outside your courses) are not detected in free text.
Images and file contents (blobs) are not redacted, only extracted text. With
mode=auto, PDFs/DOCX/text files are returned as redacted text only.Pseudonymisation is not anonymisation – think about which data you send to an AI model at all.
Files
Tools return fileRef values: e_<id> course element, a_<task>_<file> task attachment, m_<thread>_<message> message attachment, i_<course>_<bulletin>_<n> announcement image. They contain no secrets and stay valid across restarts.
itslearning_download_file modes:
| Result |
| PDF/DOCX/text → redacted text; images → image; other formats → file |
| redacted text only |
| file only (not redacted) |
| file + redacted text |
Elements that are not files (links, notes, tests) return kind: "page" with the redacted page text.
Smoke test against your account
bun run smoke # calls every tool once and checks all output for leaks
bun run smoke --details # additionally shows masked findings (e.g. "S****") and their structureThe script fetches the real names (own account, threads, news, course participants) directly from the API and checks whether any of them – or tokens, session URLs, e-mail addresses, person IDs – appear in tool output. Its output contains counts and masked structure only (letters → x, digits → 9), so it can be shared in issues. Exit code 1 on findings.
Development
bun install
bun run typecheck
bun testArchitecture, invariants and conventions: CONTRIBUTING.md, CLAUDE.md
Specification: docs/mcp-server-spec.md
API findings: docs/itslearning-api.md
Roadmap: docs/roadmap.md
Changes: CHANGELOG.md
scripts/dev/probe.ts (bun run probe) is the exploration script used to map the API; its report contains structure only.
Security
Please report vulnerabilities – especially redaction leaks – privately as described in SECURITY.md. Never post real student data in issues.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only access to a student's recorded classes: transcripts, notes, slides and concept map.
Connect AI clients to your Dactic work context through a hosted MCP service.
Read-only access to Epivo's live course catalogue for AI agents.
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables FCPS students to give MCP-compatible AI assistants read-only access to Schoology courses, materials, assignments, events, and official StudentVUE grades, including extracting text from document attachments.122MIT
- AlicenseAqualityBmaintenanceEnables AI apps to read a student's Moodle courses, upcoming and overdue due dates, assignment submission statuses, course grades, gradebook items and announcements. It is strictly read only, so it can never submit, edit or delete anything.17186 npmMIT
- AlicenseAqualityCmaintenanceEnables MCP-capable AI clients to query course announcements, deadlines, grades, and assignments and to preview or incrementally sync course materials to local storage.10MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read a user's own Canvas account data—courses, deadlines, assignments, announcements, files, syllabus, grades, and discussions—through a read-only, locally run MCP connector.20MIT