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.

Related MCP server: mcp-imap

🛠️ Installation & Setup

Prerequisites

• Python 3.11+

• uv (recommended) or pip

1. Clone & Install Dependencies

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

2. Configure Credentials

Create a .env file in the project root:

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

{
  "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

🧪 Testing

Run unit and integration tests:

uv run pytest -v

📄 License

MIT License.