# AGH Mail MCP Server

A small [MCP] server that lets **Claude** read and
send email from your AGH mailbox (`poczta.agh.edu.pl`) 

Ask Claude things like *"any new emails"* or *"reply to the professor saying I'll attend"*

> **Status:** Local use with **Claude Desktop** is fully supported and is what this
> README covers. Remote hosting (so it works in the Claude mobile/web app or Cowork)
> is not supported yet.

---

## Tools exposed

| Tool | What it does |
|---|---|
| `get_unread_emails` | List unread messages |
| `get_email_body` | Fetch the full body of one message |
| `search_emails` | Search by sender, subject, and/or date |
| `mark_as_read` | Mark a message as read |
| `send_email` | Send from your AGH address (only after you confirm) |
| `get_folders` | List all IMAP folders in the mailbox |

---

## Prerequisites

- Python 3.10 or newer
- An AGH mailbox at `poczta.agh.edu.pl`
- Claude Desktop installed

---

## Setup

### Step 1 - Generate an AGH app password

1. Log into <https://poczta.agh.edu.pl>
2. Go to **Ustawienia → Hasła do aplikacji**
3. Enter your password to authorize, give the new password a name
4. Copy the generated password (you'll only see it once)

### Step 2 - Clone and install

```bash
git clone https://github.com/Nikodem5/agh-mcp.git
cd agh-mcp
python -m venv .venv
(activate the virtual environment)
pip install -r requirements.txt
```

### Step 3 - Configure your credentials

Copy the example file and fill in your two values:

```bash
cp .env.example .env        # Windows PowerShell: Copy-Item .env.example .env
```

Edit `.env`:

```env
AGH_EMAIL=123456@student.agh.edu.pl
AGH_APP_PASS=the_app_password_from_step_1
```

### Step 4 - Connect it to Claude Desktop

Open your Claude Desktop config file (create it if it doesn't exist):

Add an entry pointing at the absolute path to `server.py`

```json
{
  "mcpServers": {
    "agh-mail": {
      "command": "python",
      "args": ["/absolute/path/to/agh-mcp/server.py"]
    }
  }
}
```

Fully quit and reopen Claude Desktop.

---

## Extending: "university agent" ideas

This is a foundation. Each new capability is just one Python function with an
`@mcp.tool()` decorator. Ideas:

- `get_calendar` — pull your AGH timetable from USOS
- `check_grades` — watch USOS for new grade entries
- `get_deadlines` — parse the UPeL e-learning platform for upcoming deadlines
- `search_library` — query the AGH library catalog

---

## Project structure

```
agh-mcp/
├── server.py                        # the MCP server (all tools live here)
├── requirements.txt                 # mcp + python-dotenv
├── .env.example                     # template — copy to .env and fill in
├── .env                             # your secrets (git-ignored, never committed)
├── .gitignore
├── cowork-skill-morning-briefing.md # optional daily-digest skill
└── README.md
```