# webuntis-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes your school's [WebUntis](https://www.webuntis.com/) data as tools. Connect it to Claude, Cursor, VS Code Copilot, or any other MCP-compatible AI client.

## Features

20 tools covering:

| Category | Tools |
|---|---|
| Timetable | today, date range, specific element, current week |
| Master data | subjects, teachers, rooms, classes, departments, holidays, timegrid, school years |
| Student | homework, exams, absences |
| Communication | news widget, inbox |
| System | status data, latest import time |

## Requirements

- Node.js 18+
- A WebUntis account (student, teacher, or parent)

## Setup

### 1. Clone and install

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

```env
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.

```env
WEBUNTIS_AUTH_MODE=secret
WEBUNTIS_USERNAME=your.username
WEBUNTIS_SECRET=BASE32SECRETHERE
```

#### Anonymous login

Some schools allow anonymous read-only access:

```env
WEBUNTIS_AUTH_MODE=anonymous
```

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

```env
WEBUNTIS_SCHOOL=yourschool
WEBUNTIS_BASEURL=yourserver.webuntis.com
```

## Usage

### Running directly

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

### Claude Desktop

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

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

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

| Tool | Description |
|---|---|
| `get_own_timetable_today` | Your timetable for today |
| `get_own_timetable_range` | Your timetable for a date range (`startDate`, `endDate`) |
| `get_own_timetable_week` | Your timetable for a full week (rich format with substitutions) |
| `get_timetable_for_element` | Timetable for any class/teacher/room by `id` and `type` (1=CLASS, 2=TEACHER, 4=ROOM) |

### Master data

| Tool | Description |
|---|---|
| `get_subjects` | All subjects |
| `get_teachers` | All teachers |
| `get_rooms` | All rooms |
| `get_classes` | All classes for a school year |
| `get_departments` | All departments |
| `get_holidays` | All holidays |
| `get_timegrid` | Daily lesson time slots |
| `get_current_schoolyear` | Current school year |
| `get_schoolyears` | All school years |

### Student

| Tool | Description |
|---|---|
| `get_homework` | Homework for a date range |
| `get_exams` | Exams for a date range (optionally filter by class, include grades) |
| `get_absences` | Your absence records for a date range |

### Communication

| Tool | Description |
|---|---|
| `get_news` | School news / messages of the day |
| `get_inbox` | Your WebUntis inbox |

### System

| Tool | Description |
|---|---|
| `get_status_data` | Lesson type color codes and cancellation statuses |
| `get_latest_import_time` | Timestamp of last data sync from the school 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