Skip to main content
Glama
itslearning-mcp
by Ludoo0
README.md
# itslearning-mcp

A read-only [Model Context Protocol](https://modelcontextprotocol.io) 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](#limits)). In particular, **file and image contents are not redacted** – only extracted text is.
- Provided "as is", without warranty (see [LICENSE](LICENSE)).

## 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`, teachers `Teacher Müller` (or `Mrs Müller`), classmates `Student-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](docs/roadmap.md)).
- Docker, or [Bun](https://bun.sh) ≥ 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:

```bash
# 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.com
```

- **Without 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_PASSWORD` from the environment are only used if `ITSL_BASE_URL` matches the checked URL.
- `--no-login` skips the account part, `--json` prints 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 |
|---|---|
| `itslearning_overview` | Starting point: overdue and upcoming tasks, recent news, unread message threads |
| `itslearning_list_courses` | Current (optionally all) courses with `courseId` and new-item counters |
| `itslearning_list_tasks` | Tasks/homework sorted by deadline; filter by course, status, due date, homework, active courses |
| `itslearning_get_task` | Task details: assignment text, deadline, submission type, attachments (`fileRef`) |
| `itslearning_list_news` | News feed across all courses or one course, optionally since a date |
| `itslearning_list_bulletins` | Announcements of a course incl. attached resources and images |
| `itslearning_list_message_threads` | Message threads with last message and unread status |
| `itslearning_get_message_thread` | Messages of a thread in chronological order, attachments as `fileRef` |
| `itslearning_list_course_files` | Folders and elements of a course (optionally recursive) with `fileRef` |
| `itslearning_download_file` | Download a file by `fileRef`: redacted text, image, or file content |

## Quick start (Docker)

```bash
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 --build
```

PowerShell: `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 /healthz` is 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):**

```bash
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`):

```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)

```bash
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_123
```

Use it from Claude Code via stdio:

```bash
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.ts
```

`DATA_DIR` (default `/data`, `.data` in `.env.example`) holds:
- `state.json` – login state (rotating refresh token; the password is never stored)
- `secret` – key for stable pseudonyms
- `teachers.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 |
|---|---|---|
| `ITSL_BASE_URL` | **required** | Your instance, e.g. `https://yourschool.itslearning.com` |
| `ITSL_USERNAME` *(file)* | **required** | itslearning user name |
| `ITSL_PASSWORD` *(file)* | **required** | itslearning password |
| `ITSL_CLIENT_ID` | mobile app client ID | OAuth client ID |
| `MCP_TRANSPORT` | `stdio` (image: `http`) | `stdio` or `http` |
| `MCP_HOST` | `127.0.0.1` (image: `0.0.0.0`) | HTTP bind address |
| `MCP_PORT` | `3000` | HTTP port |
| `MCP_API_KEY` *(file)* | required for `http` | Bearer key for clients, ≥ 32 characters |
| `MCP_ALLOWED_ORIGINS` | empty | Allowed browser origins (comma-separated); other `Origin` headers → 403 |
| `REDACTION_LANGUAGE` | `en` | Labels and placeholders: `en` or `de` |
| `REDACTION_SECRET` *(file)* | generated | HMAC secret for pseudonyms (≥ 16 characters), stored in `DATA_DIR/secret` if not set |
| `REDACTION_KEEP_WORDS` | empty | Comma-separated words never replaced as a single name (see below) |
| `REDACT_TEACHERS` | `false` | `true` → pseudonymise teachers too (`Teacher-7F3A`) |
| `TEACHER_ROLE_TITLES` | `Teacher,Staff,Lehrer,Lehrerin,Lehrkraft,Mitarbeiter` | Role titles that count as teacher (substring, case-insensitive) |
| `MAX_FILE_MB` | `25` | Maximum download size |
| `CACHE_TTL_S` | `60` | List cache lifetime |
| `MAX_CONCURRENCY` | `2` | Parallel requests to itslearning |
| `MIN_REQUEST_INTERVAL_MS` | `200` | Minimum spacing between requests |
| `DATA_DIR` | `/data` | Persistent state, secret, teacher directory, file cache |
| `DOWNLOAD_DIR` | – | Additionally save downloaded files here (redacted file name) |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |

## Privacy and redaction

How people appear in tool output:

| Who | `REDACTION_LANGUAGE=en` | `REDACTION_LANGUAGE=de` |
|---|---|---|
| Account owner | `Me` | `Ich` |
| Teacher (salutation set) | `Mrs Müller` | `Frau Müller` |
| Teacher (no salutation) | `Teacher Müller` | `Lehrkraft Müller` |
| Teacher with `REDACT_TEACHERS=true` | `Teacher-7F3A` | `Lehrkraft-7F3A` |
| Classmate | `Student-7F3A` | `Schüler:in-7F3A` |
| Unknown role | `Person-7F3A` | `Person-7F3A` |

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):

```json
{ "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:

| `mode` | Result |
|---|---|
| `auto` (default) | PDF/DOCX/text → **redacted text**; images → image; other formats → file |
| `text` | redacted text only |
| `blob` | file only (not redacted) |
| `both` | file + redacted text |

Elements that are not files (links, notes, tests) return `kind: "page"` with the redacted page text.

## Smoke test against your account

```bash
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 structure
```

The 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

```bash
bun install
bun run typecheck
bun test
```

- Architecture, invariants and conventions: [CONTRIBUTING.md](CONTRIBUTING.md), [CLAUDE.md](CLAUDE.md)
- Specification: [docs/mcp-server-spec.md](docs/mcp-server-spec.md)
- API findings: [docs/itslearning-api.md](docs/itslearning-api.md)
- Roadmap: [docs/roadmap.md](docs/roadmap.md)
- Changes: [CHANGELOG.md](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](SECURITY.md). Never post real student data in issues.

## License

[MIT](LICENSE)