<div align="center">

# UG Sakai for Claude

**Your University of Ghana Sakai account, inside Claude.**

Ask what is due, read assignment briefs, follow announcements, revise from your lecture slides,
and get help planning and reviewing your own work, all without opening Sakai.

[![CI](https://github.com/Joeboy77/ug-sakai-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Joeboy77/ug-sakai-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
![Read-only](https://img.shields.io/badge/Sakai%20access-read--only-success)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[Install](#install) · [What you can do](#what-you-can-do) · [Privacy](#privacy-and-safety) ·
[Troubleshooting](#troubleshooting) · [Contributing](CONTRIBUTING.md)

</div>

---

> **Not an official University of Ghana product.** This is an independent, open-source student
> project. It uses your own login to read what you can already see on
> [sakai.ug.edu.gh](https://sakai.ug.edu.gh), and nothing more.

## Why

Sakai keeps everything you need, but spread across dozens of course sites, tools and PDFs.
This project is an [MCP](https://modelcontextprotocol.io) server: it gives Claude a small set of
safe, read-only tools for your Sakai account, so you can simply ask:

> *"What's due in the next two weeks, and which of those haven't I submitted?"*
>
> *"Explain the DCIT 418 project brief in plain language and list the deliverables."*
>
> *"Show me slide 14 of the MATH 359 graphs lecture. I don't follow the diagram."*
>
> *"Help me revise for the MATH 359 exam and quiz me on my weak topics."*

## What you can do

### Stay on top of your courses

| Ask Claude… | Tool |
|---|---|
| "What's due soon?" (assignments **and** quiz/exam dates) | `get_upcoming_deadlines` |
| "Anything new on Sakai since yesterday?" | `whats_new` |
| "Which courses am I taking this semester?" | `list_my_courses` |
| "Any announcements from DCIT 302?" | `get_announcements` |
| "What's on my calendar this week?" | `get_calendar` |
| "What's my UG Sakai link for my phone?" | `get_phone_and_web_link` |

### Assignments, feedback and grades

| Ask Claude… | Tool |
|---|---|
| "List the assignments in DCIT 418" | `list_assignments` |
| "Show me the full brief for assignment 2" | `get_assignment_details` |
| "Read the PDF attached to that assignment" | `download_assignment_attachment` |
| "What feedback did my lecturer give me?" | `get_assignment_feedback` |
| "What grades have been released in DCIT 302?" | `get_my_grades` |

### Lecture material

| Ask Claude… | Tool |
|---|---|
| "List the slides in MATH 359" | `list_course_resources` |
| "Summarise Lecture 3" (PDF, PowerPoint, Word, text) | `get_resource` |
| "Give me the download link for the assignment brief" | Every file comes with a direct download link that works without logging in to Sakai |
| "Show me page 12 as a picture" (equations, diagrams, handwriting) | `view_slide` |
| "Does this course use Lessons?" | `list_lessons` |

### Study with built-in prompts

In Claude Desktop, click **+** and choose **UG Sakai** to start one of these:

| Prompt | What Claude does |
|---|---|
| **Break down an assignment** | Explains what is really being asked, the deliverables, criteria and deadline. |
| **Plan an assignment** | Builds a step-by-step plan with mini-deadlines, fitted around your other deadlines. |
| **Tutor me for an assignment** | Teaches the concepts from your course's own lecture files and checks your understanding. |
| **Review my draft** | Gives specific feedback on your draft against the brief, including Turnitin risks. |
| **Help me draft it myself** | Guides you part by part while **you** write. |
| **Revise for an exam** | Builds a revision plan up to the exam date, finds past papers and quizzes you one question at a time. |

### Optional: submission checker

UG Sakai does not let tools submit work, and this project never will. If you switch on the
checker, Claude can confirm a file **you** chose is ready (right type and size, assignment still
open, resubmission allowed), then gives you the link and the steps to submit it yourself.

## Use it on claude.ai (nothing to install, about 2 minutes)

1. On [claude.ai](https://claude.ai) open **Settings → Connectors → Add custom connector**.
2. Name it `Sakai-MCP` and paste `https://apisakaimcp.klare.app/mcp` as the MCP server URL.
   Click **Continue**, then **Connect**.
3. Sign in with your **Student ID** and **Sakai password**.

It now works on claude.ai in any browser and in the Claude phone app. The hosted server stores your
Student ID and password encrypted so it can sign you back in to Sakai; if you'd rather your password
never leaves your computer, use the Claude Desktop install below. Step-by-step guide:
[sakaimcp.klare.app/start](https://sakaimcp.klare.app/start).

To run your own hosted server, deploy this repository's `Dockerfile` (see `render.yaml`) with
`SAKAI_MCP_SECRET_KEY` set to a long random value and a persistent disk mounted at `/data`.

## Install on Claude Desktop (private option)

You need [Claude Desktop](https://claude.ai/download).

### Option 1: one file (recommended, about 3 minutes)

1. Download **`ug-sakai.mcpb`** from the [latest release](https://github.com/Joeboy77/ug-sakai-mcp/releases/latest).
2. Double-click it. Claude Desktop opens an install screen.
3. Enter your **Student ID** and **Sakai password**, and switch on the submission checker if you
   want it. Click **Install**.
4. Open a new chat and ask: *"Which courses am I taking this semester?"*

The first start takes up to a minute while Claude Desktop sets things up. To change your
password later, go to **Settings → Extensions → UG Sakai**.

### Option 2: from source

<details>
<summary>Manual install with uv (about 10 minutes)</summary>

1. **Install [uv](https://docs.astral.sh/uv/)**. It also installs the right Python.

   macOS or Linux:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
   Windows (PowerShell):
   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

2. **Get the code**
   ```bash
   git clone https://github.com/Joeboy77/ug-sakai-mcp.git
   cd ug-sakai-mcp
   uv sync
   ```

3. **Save your Sakai login** in your system keychain. Type it in the terminal, never in a chat.
   ```bash
   uv run ug-sakai-mcp login
   uv run ug-sakai-mcp check
   ```

4. **Connect Claude Desktop**
   ```bash
   uv run ug-sakai-mcp desktop-config
   ```
   Paste the printed `ug-sakai` block into **Settings → Developer → Edit Config** under
   `mcpServers`, save, then quit Claude Desktop completely and reopen it. Add
   `--enable-submission` to switch on the submission checker.

</details>

## Use it on claude.ai and the Claude phone app

No terminal needed. Claude Desktop runs UG Sakai on your computer and can also share it, privately,
with claude.ai in any browser and with the Claude phone app.

1. In Claude Desktop open **Settings → Extensions → UG Sakai**, turn on **Use on claude.ai and my
   phone**, and save. Quit Claude Desktop completely and open it again.
2. In a Claude Desktop chat, ask: *"What's my UG Sakai link for my phone?"* Claude replies with your
   connector address, like `https://quiet-river-1234.trycloudflare.com/mcp`.
3. On claude.ai open **Settings → Connectors → Add custom connector**. Name it `UG Sakai`, paste
   the address and click **Continue**, then **Connect**.
4. A UG Sakai sign-in page opens. Enter your **Student ID** and **Sakai password** and click
   **Connect**. It's checked against the login already saved on your computer, so a wrong guess
   never reaches Sakai and can't lock your account.

It now works on claude.ai and in the Claude phone app, signed in to the same Claude account.

Good to know:

- **Your computer must be on, online and running Claude Desktop** (the window can be closed) for
  the website and phone to reach it.
- **The free address changes when Claude Desktop restarts.** If the connector stops working, ask
  Claude Desktop for the link again and update the connector's address on claude.ai.
- **How it connects:** UG Sakai opens a free [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
  from your computer, downloading `cloudflared` from Cloudflare's GitHub releases the first time
  if it isn't installed. Nothing is opened on your router.
- **Only you can connect.** Every new client must sign in with your Student ID and password, the
  sign-in page locks for 10 minutes after five wrong tries, and tokens expire and rotate. To sign
  every client out, delete `~/SakaiMCP/remote/oauth.json`, or run `uv run ug-sakai-mcp remote-reset`.

From a terminal, the same thing runs with `uv run ug-sakai-mcp remote --tunnel`, or with your own
stable address (a Cloudflare tunnel on your domain, [Tailscale Funnel](https://tailscale.com/kb/1223/funnel)
or an [ngrok static domain](https://ngrok.com/docs/getting-started/)) pointed at `http://127.0.0.1:8765`:
`uv run ug-sakai-mcp remote --url https://your-address`.

## Privacy and safety

| | |
|---|---|
| **Read-only by design** | Every Sakai address the server may call is on a fixed allowlist of read endpoints. Anything else is refused before a request is made, including Sakai actions that change data. |
| **Your password stays with you** | Stored in your system keychain (macOS Keychain, Windows Credential Manager). It is only ever sent to `sakai.ug.edu.gh`. |
| **No lockouts** | If Sakai rejects your password, the server stops and never retries, so your account is not locked. |
| **Nothing leaves your computer** | No servers, accounts or analytics. Files Claude reads are saved to `~/SakaiMCP/downloads`. |
| **Prompt-injection guard** | Text from announcements, briefs and files is marked as untrusted, and Claude is told never to follow instructions inside it. |
| **Safe downloads** | Course files only, from Sakai only, with cleaned filenames and a 50 MB limit. Download links are signed, unguessable and expire after 24 hours. |

What is stored where:

| What | Where |
|---|---|
| Your login | System keychain |
| Files Claude reads | `~/SakaiMCP/downloads/<course>/…` |
| What `whats_new` has already shown you | `~/SakaiMCP/state.json` |
| Submission checks | `~/SakaiMCP/logs/submissions.jsonl` |
| Debug log (only with `DEBUG=true`) | `~/SakaiMCP/logs/server.log` (passwords and sessions masked) |

To remove everything, uninstall the extension (or run `uv run ug-sakai-mcp forget`), then delete
the `~/SakaiMCP` folder.

## Academic integrity

You are responsible for everything you submit, and UG checks submissions with Turnitin. The
built-in prompts tell Claude to help you **understand and produce the work yourself**, to explain
so you can defend every part, and to warn you first when a brief limits or bans AI tools. The
server cannot take quizzes, read quiz questions or submit anything, and the revision prompt
refuses to answer questions from a quiz that is open right now. Always follow your lecturer's
rules.

## How it works

```mermaid
flowchart LR
    You([You]) --> Claude[Claude Desktop]
    Claude <-->|MCP over stdio| Server[UG Sakai MCP server<br/>on your computer]
    Server -->|login from keychain| Keychain[(System keychain)]
    Server -->|read-only allowlist| Sakai[(sakai.ug.edu.gh<br/>/direct REST API)]
    Server -->|text and page images| Files[(~/SakaiMCP/downloads)]
```

The server logs in to Sakai's `/direct` REST API with your session, reads only allowlisted
endpoints, turns the results into compact, structured answers with dates in Ghana time, and
extracts text and page images from lecture files. [`DISCOVERY.md`](DISCOVERY.md) records what UG
Sakai supports and why each design decision was made.

## Limitations

- **No quiz or exam scores.** UG Sakai only shares assignment grades with tools.
- **No submitting, posting or messaging.** By design.
- **Lessons pages:** page titles only for now.
- **Old `.ppt` and `.doc` files and images** cannot be read as text. `view_slide` shows PDF pages,
  and the pictures inside PowerPoint slides.
- **Scanned PDFs** have no text layer. Use `view_slide` to let Claude look at the page instead.

## Troubleshooting

| You see | Do this |
|---|---|
| "Sakai rejected the Student ID or password" | Update your login in **Settings → Extensions → UG Sakai** (or `uv run ug-sakai-mcp login`) and restart Claude Desktop. |
| "Login is paused…" | Same as above. The server pauses after one rejection to protect your account. |
| "Sakai is not responding" | Check your internet connection, or try again later. Sakai may be down. |
| "No Sakai Student ID and password are set yet" | Add them in the extension settings, or run `uv run ug-sakai-mcp login`. |
| "This computer has no usable keychain" | Copy `.env.example` to `.env` and set `SAKAI_USERNAME` and `SAKAI_PASSWORD`. Never share that file. |
| The tools don't appear in Claude | Quit Claude Desktop completely (Cmd+Q on a Mac) and reopen it. For a manual install, rerun `uv run ug-sakai-mcp desktop-config` and check the paths. |
| "matches more than one course" | You took the course in more than one year. Use the `site_id` from `list_my_courses`. |

## FAQ

**Does it work with other universities' Sakai?** It is built and tested for UG Sakai. Other Sakai
sites may work by setting `SAKAI_BASE_URL`, but their enabled endpoints differ. Run
`uv run ug-sakai-discover` first.

**Can it see other students' work or grades?** No. It uses your login, so it only sees what you
can already see on Sakai.

**Does it work with Claude Code or other MCP clients?** Yes. Any client that can start a stdio MCP
server can run `uv run ug-sakai-mcp`.

## Contributing

Contributions are welcome, from bug reports to new tools. Start with
[CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, see [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)