Exmail MCP Setup

Set up a Tencent enterprise email MCP connector for WorkBuddy. Use this when the user wants to connect exmail to read and search emails. Replaces the broken mcp-email npm package.

Tencent Enterprise Email MCP Setup

Set up a custom MCP server to connect Tencent enterprise email (exmail.qq.com) to WorkBuddy. Provides three tools: get_recent_emails, search_emails, get_email_content.

Prerequisites

Two pieces of information are required from the user:

1. Email address: e.g. [e-mail]
2. Auth code (客户端专用密码): generated in exmail admin panel, NOT the login password. Path: exmail.qq.com → Settings → Account → Client-specific password → Generate

Ask for these if not provided. The email type is always exmail, do not ask about it.

Why Not Use the mcp-email npm Package

The mcp-email package on npm is broken for WorkBuddy:

1. stdout pollution: Contains console.log() calls that write to stdout, corrupting MCP's JSON-RPC protocol over stdio. MCP requires stdout to carry only JSON-RPC messages.
2. NODE_OPTIONS conflict: WorkBuddy's runtime sets NODE_OPTIONS=--use-system-ca which modern Node.js rejects, killing the process immediately.
3. Old MCP SDK: Uses SDK v0.6.1, incompatible with current WorkBuddy's MCP client.

Do NOT use mcp-email. Always deploy the custom server below.

Deployment Steps

Step 1: Create the MCP server directory

mkdir -p ~/.workbuddy/mcp-servers/exmail-mcp

Step 2: Copy the reference server code

The working server code is at references/index.js in this skill. Copy it:

cp <skill-path>/references/index.js ~/.workbuddy/mcp-servers/exmail-mcp/index.js

Step 3: Install dependencies

Use the managed Node.js binary, NOT the system one:

cd ~/.workbuddy/mcp-servers/exmail-mcp
~/.workbuddy/binaries/node/versions/22.12.0/bin/npm init -y
~/.workbuddy/binaries/node/versions/22.12.0/bin/npm pkg set type=module
~/.workbuddy/binaries/node/versions/22.12.0/bin/npm install @modelcontextprotocol/sdk imap mailparser nodemailer dotenv

Step 4: Configure mcp.json

Read ~/.workbuddy/mcp.json first to check for existing MCP servers. Add the exmail entry to the mcpServers object:

{
  "mcpServers": {
    "exmail": {
      "command": "$HOME/.workbuddy/binaries/node/versions/22.12.0/bin/node",
      "args": [
        "$HOME/.workbuddy/mcp-servers/exmail-mcp/index.js"
      ],
      "env": {
        "EMAIL_USER": "<[e-mail]>",
        "EMAIL_PASSWORD": "<auth-code>",
        "NODE_OPTIONS": "",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Key points:

• Use absolute paths to the managed Node.js binary. Never use npx.
• "NODE_OPTIONS": "" is CRITICAL — clears the --use-system-ca that crashes the process.
• "NODE_TLS_REJECT_UNAUTHORIZED": "0" avoids TLS issues on exmail IMAP.

Step 5: Tell the user to enable the connector

After writing mcp.json, tell the user:

• Open WorkBuddy connector management page
• Find exmail entry
• Click "Trust" (信任) to enable

Step 6: Verify

After the user enables it, test with the mcp__exmail__get_recent_emails tool (or search_emails / get_email_content).

Common Errors

Error	Cause	Fix
Connection closed (-32000)	stdout polluted or NODE_OPTIONS conflict	Verify NODE_OPTIONS: "" in env and no console.log in index.js
Process exits immediately	stdin EOF	Normal — WorkBuddy keeps pipe open, only fails in manual < /dev/null tests
imap module not found	Missing dependency	Re-run npm install in the server directory
Login failed	Wrong password	Use auth code (客户端专用密码), not login password

How to Test Before Enabling (Optional)

Use a Node.js spawn test script instead of piping to stdin — piping won't work because the MCP server reads from stdin and a pipe that closes will kill it:

import { spawn } from 'child_process';
const s = spawn(nodePath, [serverPath], {
  env: { EMAIL_USER: '...', EMAIL_PASSWORD: '...', NODE_OPTIONS: '', NODE_TLS_REJECT_UNAUTHORIZED: '0' },
  stdio: ['pipe', 'pipe', 'pipe']
});
s.stdout.on('data', d => console.log(d.toString()));
s.stderr.on('data', d => console.error('STDERR:', d.toString()));
s.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0'}}}) + '\n');

If the response includes "result":{"protocolVersion":"2024-11-05"...}, the server is working.