npm package: @stone64/qqmail-mcp
Description: Read-only MCP server for QQMail via IMAP (stdio)
Author: stone
Latest version: 0.1.0

# qqmail-mcp (stdio)

Read-only MCP server for QQMail via IMAP.

## Setup

### 1. Enable IMAP in QQ Mail

1. Log in to [QQ Mail](https://mail.qq.com/)
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:

```bash
QQMAIL_USER=your_qq_email@qq.com
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:
```bash
npm install
```

Build:
```bash
npm run build
```

Start server:
```bash
npm start
```

Dev mode (with auto-reload):
```bash
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):
```bash
mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5
```

List with snippets:
```bash
mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5 includeSnippet=true
```

List with custom snippet length:
```bash
mcporter call --stdio "node dist/index.js" qqmail_list_new_messages limit=5 includeSnippet=true maxLen=100
```

List messages since a date (recommend timezone):
```bash
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:
```bash
mcporter call --stdio "node dist/index.js" qqmail_get_snippet id=12345
```

Get full message:
```bash
mcporter call --stdio "node dist/index.js" qqmail_get_message id=12345
```

Get full message with HTML:
```bash
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)