webuntis-mcp

A Model Context Protocol (MCP) server that exposes your school's WebUntis data as tools. Connect it to Claude, Cursor, VS Code Copilot, or any other MCP-compatible AI client.

Features

20 tools covering:

Related MCP server: tbank-edu-mcp

Requirements

• Node.js 18+

• A WebUntis account (student, teacher, or parent)

Setup

1. Clone and install

git clone <this-repo>
cd webuntis-mcp
npm install
npm run build

2. Find your school details

Open WebUntis in a browser. Your URL looks like:

https://mese.webuntis.com/WebUntis/?school=gymkirchheim#/basic/login

• WEBUNTIS_BASEURL = mese.webuntis.com (the hostname)

• WEBUNTIS_SCHOOL = gymkirchheim (the ?school= value)

3. Configure environment variables

Create a .env file or set the variables in your shell / MCP host config.

WEBUNTIS_SCHOOL defaults to hss and WEBUNTIS_BASEURL defaults to hss.webuntis.com, so you only need to set credentials.

Password login (most common)

WEBUNTIS_USERNAME=your.username
WEBUNTIS_PASSWORD=your.password

QR / OTP / Secret login

Generate a secret from the WebUntis app: Profile → Data Access → Display QR Code. Use the secret value shown there.

WEBUNTIS_AUTH_MODE=secret
WEBUNTIS_USERNAME=your.username
WEBUNTIS_SECRET=BASE32SECRETHERE

Anonymous login

Some schools allow anonymous read-only access:

WEBUNTIS_AUTH_MODE=anonymous

Overriding school/server (if needed for a different school)

WEBUNTIS_SCHOOL=yourschool
WEBUNTIS_BASEURL=yourserver.webuntis.com

Usage

Running directly

WEBUNTIS_SCHOOL=... WEBUNTIS_BASEURL=... WEBUNTIS_USERNAME=... WEBUNTIS_PASSWORD=... node dist/index.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "webuntis": {
      "command": "node",
      "args": ["/absolute/path/to/webuntis-mcp/dist/index.js"],
      "env": {
        "WEBUNTIS_USERNAME": "your.username",
        "WEBUNTIS_PASSWORD": "your.password"
      }
    }
  }
}

Kiro CLI

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "webuntis": {
      "command": "node",
      "args": ["/absolute/path/to/webuntis-mcp/dist/index.js"],
      "env": {
        "WEBUNTIS_USERNAME": "your.username",
        "WEBUNTIS_PASSWORD": "your.password"
      }
    }
  }
}

Cursor / VS Code

Add the same JSON block to your MCP settings file for that editor.

Available Tools

Timetable

Master data

Student

Communication

System

Example prompts

• "What do I have today?"

• "Show me my homework for this week."

• "Are there any exams coming up in October?"

• "When are the next holidays?"

• "What lessons does class 10A have on Monday?"

• "Do I have any unexcused absences?"

License

MIT