qqmail-mcp (stdio)

Read-only MCP server for QQMail via IMAP.

Setup

1. Enable IMAP in QQ Mail

1. Log in to QQ Mail
2. Go to Settings (设置) → Account (账户)
3. Find POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV Service section
4. Enable IMAP/SMTP Service (IMAP/SMTP服务)
5. Click Generate Authorization Code (生成授权码)
6. Follow the SMS verification process
7. Save the authorization code - this is your IMAP password (NOT your QQ password)

2. Configure Environment

Create .env file in project root:

[email protected]
QQMAIL_PASS=your_authorization_code_here
QQMAIL_IMAP_HOST=imap.qq.com
QQMAIL_IMAP_PORT=993
QQMAIL_IMAP_SECURE=true
QQMAIL_FOLDER=INBOX

Important: Use the authorization code from step 1, not your QQ password.

Build & Run

Install dependencies:

npm install

Build:

npm run build

Start server:

npm start

Dev mode (with auto-reload):

npm run dev

Tools

qqmail_list_new_messages

List newest messages in a folder (read-only).

Parameters:

• folder (string, default: "INBOX"): IMAP folder name
• limit (number, default: 20, max: 50): Number of messages to return
• since (string, optional): ISO 8601 datetime filter (e.g., "2026-03-08T00:00:00+08:00")
• includeSnippet (boolean, default: false): Whether to fetch text preview
• maxLen (number, default: 240, max: 1000): Max snippet length when includeSnippet=true

Returns: Array of messages with fields:

• id (string): IMAP UID
• from (string): Sender (name + email)
• subject (string): Email subject
• date (string): ISO 8601 datetime
• snippet (string): Text preview (empty if includeSnippet=false)

Performance Note: Set includeSnippet=false (default) for fast listing. Only enable when you need previews.

qqmail_get_snippet

Get text preview of a message by UID.

Parameters:

• folder (string, default: "INBOX"): IMAP folder name
• id (string, required): UID from qqmail_list_new_messages
• maxLen (number, default: 240, max: 1000): Max snippet length

Returns: Plain text snippet (prefers text body, falls back to HTML→text).

qqmail_get_message

Get full message by UID (read-only).

Parameters:

• folder (string, default: "INBOX"): IMAP folder name
• id (string, required): UID from qqmail_list_new_messages
• includeHtml (boolean, default: false): Whether to include HTML body

Returns: Object with fields:

• id (string): IMAP UID
• folder (string): Folder name
• date (string): ISO 8601 datetime
• from (string): Sender
• to (string): Recipients
• subject (string): Subject
• text (string): Plain text body
• html (string, optional): HTML body (if includeHtml=true)
• headers (object): All email headers

mcporter Examples

List 5 newest messages (fast, no snippets):

mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5

List with snippets:

mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5 includeSnippet=true

List with custom snippet length:

mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5 includeSnippet=true maxLen=100

List messages since a date (recommend timezone):

mcporter call --stdio "node dist/index.js" qqmail_list_new_messages since="2026-03-08T00:00:00+08:00"

Get snippet for a specific message:

mcporter call --stdio "node dist/index.js" qqmail_get_snippet id=12345

Get full message:

mcporter call --stdio "node dist/index.js" qqmail_get_message id=12345

Get full message with HTML:

mcporter call --stdio "node dist/index.js" qqmail_get_message id=12345 includeHtml=true

Common Errors & Troubleshooting

"Missing env: QQMAIL_USER" or "Missing env: QQMAIL_PASS"

• Cause: Environment variables not set
• Fix: Create .env file with QQMAIL_USER and QQMAIL_PASS

"Authentication failed" or "Invalid credentials"

• Cause: Wrong authorization code or IMAP not enabled
• Fix:
  1. Verify IMAP is enabled in QQ Mail settings
  2. Use the authorization code, not your QQ password
  3. Generate a new authorization code if needed

"Mailbox does not exist" or "Unknown Mailbox"

• Cause: Invalid folder name
• Fix:
  • Use "INBOX" for inbox (default)
  • Common folders: "Sent Messages", "Drafts", "Trash"
  • Folder names are case-sensitive

"since must be ISO 8601 datetime"

• Cause: Invalid date format in since parameter
• Fix: Use ISO 8601 format with timezone, e.g., "2026-03-08T00:00:00+08:00"

Connection timeout

• Cause: Network issues or firewall blocking port 993
• Fix:
  • Check internet connection
  • Verify port 993 (IMAP SSL) is not blocked
  • Try from a different network

Notes

• This is a read-only server (no mark_read / move / delete / flag operations)
• id values are IMAP UIDs (unique within a folder)
• For best performance, use includeSnippet=false when listing messages
• Recommend including timezone in since parameter (e.g., +08:00 for Beijing time)