FudanMailBox MCP

A small, privacy-conscious MCP server for Fudan Cloud Mail (@m.fudan.edu.cn) and compatible Tencent Enterprise Mail accounts.

It uses standard IMAP over SSL for mailbox operations and SMTP over SSL for sending. Credentials are read from operating-system environment variables and are never stored in this repository.

Community project. Not an official Fudan University or Tencent project.

Features

Mailbox

• List folders and special-use folders (Inbox, Drafts, Sent, Trash, Junk when advertised)

• Folder total/unread counts

• List newest mail without marking it read

• Search by text, sender, recipient, subject, date range, unread/starred

• Read plain-text content, optional HTML, headers, attachment inventory

• Download attachments

• Mark read/unread and starred/unstarred

• Move, archive, trash, or permanently delete messages

• Create, rename, and delete folders

Drafts

• Save server-side drafts through IMAP

• Replace/update an existing draft

• Drafts support To/Cc/Bcc, plain text, optional HTML, and attachments

Sending

• Send To/Cc/Bcc mail

• Plain-text and optional HTML body

• File attachments

• Reply / reply-all

• Forward, optionally including original attachments

• Configurable approved sender aliases

• dry_run=true by default for send/reply/forward so an agent can show a preview first

• Optional copy to the server Sent folder

Contacts

The public v0.1 implementation deliberately does not reverse-engineer Tencent Webmail contacts.

Instead it provides a local private contact book, stored outside this Git repository:

• list/search contacts

• add/update/delete contacts

• import recent correspondents from message headers

Native Tencent/Fudan contact and calendar sync is intentionally left for a future Exchange-compatible module.

Related MCP server: qqconnect

Not implemented in v0.1

These are not standard IMAP/SMTP features:

• Native Tencent/Fudan webmail contact synchronization

• Exchange calendar synchronization / meeting invitations

• Webmail-only mail recall

• Delivery-status query

• 2 GB webmail large-attachment transfer

• Webmail notes, to-do, microdisk/docs/file-transfer features

Requirements

• Python 3.11+

• Fudan Cloud Mail account

• Client protocol enabled in webmail settings

• Client-specific password if secure login is enabled

Default servers:

• IMAP: imap.exmail.qq.com:993 with SSL

• SMTP: smtp.exmail.qq.com:465 with SSL

Installation

git clone https://github.com/BuddyKang/FudanMailBox_MCP.git
cd FudanMailBox_MCP

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Run directly:

.\.venv\Scripts\python.exe -m fudanmailbox_mcp

Windows credential setup

Do not paste the client-specific password into config.json, README.md, .env, source code, Git, or an issue.

Set Windows user environment variables:

[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_USER",
  "YOUR_STUDENT_ID@m.fudan.edu.cn",
  "User"
)

[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_APP_PASSWORD",
  "YOUR_CLIENT_SPECIFIC_PASSWORD",
  "User"
)

Optional approved From aliases:

[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_FROM_ALIASES",
  "alias1@m.fudan.edu.cn,alias2@m.fudan.edu.cn",
  "User"
)

After changing environment variables, fully restart DSH / Super-MCP so the child MCP process inherits them.

Windows GUI path:

Search "Edit environment variables for your account" -> Environment Variables -> User variables

Create:

• FUDAN_MAIL_USER

• FUDAN_MAIL_APP_PASSWORD

Super-MCP example

{
  "mcpServers": {
    "fudanmailbox": {
      "command": "C:\\path\\to\\FudanMailBox_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fudanmailbox_mcp"]
    }
  }
}

No credentials are written into this config. The process inherits Windows user environment variables.

Recommended agent policy

Read-only operations can usually be allowed.

Treat these as consequential:

• send_message / reply_message / forward_message: preview first, then send

• delete_message(permanent=true): require explicit confirmation

• delete_folder: require explicit confirmation

• update_draft: require confirmation before replacing the old draft

• delete_contact: require explicit confirmation

The server also has conservative defaults such as dry_run=true for outbound mail and confirmation gates for destructive actions.

Main MCP tools

• capabilities

• account_status

• test_connection

• list_folders

• folder_status

• list_messages

• search_messages

• get_message

• download_attachment

• set_message_flags

• move_message

• archive_message

• delete_message

• create_folder

• rename_folder

• delete_folder

• save_draft

• update_draft

• send_message

• reply_message

• forward_message

• list_sender_aliases

• list_contacts

• search_contacts

• upsert_contact

• delete_contact

• import_correspondents

Environment variables

Security

See SECURITY.md. Never commit credentials, exported session cookies, saved webmail HTML containing live session identifiers, private contact databases, or downloaded mail/attachments.

License

MIT