# METU Webmail MCP Server 📨

A Model Context Protocol (MCP) server for **Middle East Technical University (METU / ODTÜ) Webmail** (`https://webmail.metu.edu.tr`).

Connect your AI assistants (Claude Desktop, Cursor, Antigravity, OpenCode, etc.) to your METU email account to list, search, read, send, reply to, flag, and organize emails securely using METU's official IMAP and SMTP servers.

---

## ✨ Features

- 📥 **Inbox & Folder Management**: List all mailboxes (`INBOX`, `Sent`, `Drafts`, `Trash`, custom folders) and check unread message counts.
- 🔍 **Advanced Email Search**: Filter messages by keyword query, sender, recipient, subject, date ranges (`SINCE`, `BEFORE`), and read/flagged status.
- 📖 **Clean Content Reading**: Robust RFC2047 decoding for Turkish characters (UTF-8, ISO-8859-9, windows-1254), automatic HTML to clean Markdown conversion, and message threading metadata.
- 📎 **Attachment Support**: Inspect attachment metadata and download/extract file attachments.
- ✉️ **Send, Reply & Forward**: Send new emails via SMTP (with automatic save to `Sent`), reply with automatic threading headers (`In-Reply-To`, `References`, `Re:` prefix), and forward messages.
- 🏷️ **Flag & Organize**: Mark emails as read/unread or starred/flagged, and move or delete messages.
- 🚀 **Dual Transport**: Supports standard MCP `stdio` mode and `sse` HTTP streaming mode.

---

## 🛠️ Installation & Setup

### Prerequisites
- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`

### 1. Clone & Install Dependencies

```bash
cd /Users/ates/Documents/projects/metu-webmail-mcp
uv sync
```

### 2. Configure Credentials

Create a `.env` file in the project root:

```env
METU_USERNAME=e123456@metu.edu.tr
METU_PASSWORD=your_metu_password

# Optional configurations (defaults shown)
METU_IMAP_SERVER=imap.metu.edu.tr
METU_IMAP_PORT=993
METU_SMTP_SERVER=smtp.metu.edu.tr
METU_SMTP_PORT=587
```

> **Note**: Both `METU_USERNAME` / `METU_PASSWORD` and `SAIS_USERNAME` / `SAIS_PASSWORD` are automatically supported.

---

## 🤖 MCP Client Configuration

### Claude Desktop / Antigravity / Cursor

Add the following to your MCP client configuration (`claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "metu-webmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/ates/Documents/projects/metu-webmail-mcp",
        "run",
        "metu-webmail-mcp"
      ],
      "env": {
        "METU_USERNAME": "e123456@metu.edu.tr",
        "METU_PASSWORD": "your_password"
      }
    }
  }
}
```

---

## 🧰 Available Tools

| Tool | Description |
| :--- | :--- |
| `get_mailbox_status` | Returns overall account summary, email address, all folder metrics, and total unread count. |
| `list_folders` | Lists all mailbox folders with total and unread email counts. |
| `list_emails` | Lists recent emails from a folder (e.g. `INBOX`, `Sent`) with pagination (`limit`, `offset`) and preview snippets. |
| `search_emails` | Searches emails by text query, sender, recipient, subject, date ranges, unread only, or flagged only. |
| `read_email` | Reads full email content, decoded headers, markdown/html body, attachments list, and optionally marks as read. |
| `get_attachment` | Downloads/extracts attachment base64 content by filename or index. |
| `send_email` | Sends an email via METU SMTP with optional HTML body, CC, BCC, and file attachments. |
| `reply_email` | Replies to an existing email with automatic message threading and quoting. |
| `forward_email` | Forwards an existing email with optional comments to new recipients. |
| `mark_email` | Updates flags (read/unread, flagged/starred). |
| `move_email` | Moves an email from one folder to another. |
| `delete_email` | Moves an email to Trash or permanently deletes it. |

---

## 🧪 Testing

Run unit and integration tests:

```bash
uv run pytest -v
```

---

## 📄 License

MIT License.