Content
# utol-mcp
A personal MCP server that allows interaction with the University of Tokyo's Learning Management System **UTOL (UTokyo LMS)** from MCP clients (e.g., Claude Desktop). Enables natural language queries for registered courses, deadlines, announcements, materials, and assignments.
Local execution is assumed, and the functionality is primarily read-only. Authentication is performed by the user through the official UTokyo Account login screen, and the tool does not handle passwords or MFA codes.
## Capabilities
- List of registered courses (timetable), announcements, and material links
- Cross-course deadline list for assignments and tests, and detailed assignment information
- Syllabus (UTAS) lookup, and search for courses outside of registered ones (public catalog information only)
- Individual download of material files
- Toggle assignment submission requirement, course registration, and deregistration (with confirmation)
## Setup
### 1. Installation and Login
To execute using npx:
```bash
npx -y utol-mcp login
```
A browser will open, prompting login with your UTokyo Account. Once confirmed, subsequent executions will not require re-authentication (sessions are saved in `~/.utol-mcp/`).
> **Status Check and Logout**
> ```bash
> npx -y utol-mcp auth-status # Check login status
> npx -y utol-mcp logout # Delete session and cache
> ```
### 2. Register with MCP Client
Add the following to your MCP client settings file (e.g., Claude Desktop):
```json
{
"mcpServers": {
"utol": { "command": "npx", "args": ["-y", "utol-mcp", "serve"] }
}
}
```
After registration, you can query the client in natural language, such as "What are the deadlines for assignments this week?" or "Show me announcements for [course name]."
## Provided Tools
Read-only tools.
| Tool | Description | Main Arguments |
|---|---|---|
| `auth_status` | Check login status | — |
| `list_courses` | List registered courses (timetable) | `refresh?` |
| `get_course` | Course details (announcements, materials, assignments) | `idnumber` |
| `list_assignments` | Cross-course assignments and tests list with deadlines | `refresh?` |
| `get_assignment` | Assignment details (read-only) | `idnumber`, `url` |
| `get_syllabus` | Syllabus (UTAS lookup) | `idnumber`, `syllabusUrl?` |
| `search_courses` | Course search (outside registered courses, public catalog info only) | `keyword?`, `teacher?`, `year?` |
| `download_material` | Single material file download | `idnumber`, `resourceId`, `destPath` |
| `list_messages` | Message list (meta only, no content) | `refresh?` |
| `refresh_cache` | Re-fetch major lists | — |
- `get_course` / `get_assignment` / `download_material` are limited to registered courses.
- `download_material` targets are specified by `materials[].resourceId` returned by `get_course`.
- Courses outside registered ones can only access public catalog information and syllabi.
### Write Operations
Operations that change state. If `confirm:true` is not present, execution is skipped, and only a preview is returned. Execution logs are recorded in `~/.utol-mcp/audit.log`. Especially, `unregister_course` affects course registration and submissions.
| Tool | Description | Reversible |
|---|---|---|
| `set_task_no_submission` | Toggle assignment submission requirement | Reversible |
| `register_course` | Register a course | Can be deregistered |
| `unregister_course` | Deregister a course | Caution (potential data loss) |
## Policy
- For personal learning support, not for mass access or material collection.
- Does not bypass UTokyo SSO, MFA, CAPTCHA, access control, or rate limiting.
- Authentication is performed by the user through the official login screen; the tool does not collect, store, or input credentials.
- Courses outside registered ones can only access public catalog information and syllabi; protected internal content is not accessed.
- Session information is stored as sensitive information in `~/.utol-mcp/` (permissions 700); do not include it in Git, logs, or cloud storage.
- Users must comply with university regulations, UTOL usage guidelines, and relevant laws.
- This tool is provided without warranty; developers assume no responsibility for damages or disadvantages. Use at your own risk.
See [`docs/AUTHENTICATION_POLICY.md`](docs/AUTHENTICATION_POLICY.md) for details.
## Authentication Mechanism
UTOL app sessions are lost when the browser is closed, but the persistent UTokyo Account (Microsoft SSO) session established by `utol-mcp login` remains on the terminal. Subsequent tool executions re-establish the session through redirects without credentials or MFA. If credentials, MFA, or account selection are requested during re-authentication, the process is aborted, and manual login is prompted. See [`docs/AUTHENTICATION_POLICY.md`](docs/AUTHENTICATION_POLICY.md) for details.
## Development
Built with TypeScript. Automatic build to `dist/` via `npm install`'s `prepare` script enables npx execution. For local development:
```bash
npm install # Dependencies + Chromium download + auto-build
npm run build # Rebuild to reflect changes
npm test # Parser and date normalization unit tests
npm run typecheck
node dist/index.js login # Local build execution example
```
To register a local build with an MCP client, specify `serve` as:
```json
{ "command": "node", "args": ["/absolute/path/to/utol-mcp/dist/index.js", "serve"] }
```
Major flows (login, re-authentication, timetable/assignments/courses/syllabus/search/material download) against the actual UTOL have been verified. Real HTML is saved in `test/fixtures/raw/` (`.gitignore`d) to determine parser selectors. When UTOL screen changes, update HTML in that directory and re-check the parser.
## License
MIT
