ai-mail-mcp

Connect your private domain email to any MCP client for email services. Supports sending (automatically appends a personal signature / brand introduction page link), receiving, reading email content, and connection testing.

Compatible with WorkBuddy, Claude Desktop, Cursor, and all tools that support the MCP protocol. Through cloud deployment, WorkBuddy desktop and mobile can share the same email entry point, allowing you to manage your email affairs with natural language anytime, anywhere.

Features

• ✉️ send_email: Send emails, automatically appending a personal signature "Sent by xx via xx" (includes an introduction page link, which can serve as a personal IP entry point)

• 📥 get_recent_emails: Get a list of emails from the last N days (subject / sender / time)

• 📖 get_email_content: Read the full email body and attachment information by UID

• 🔌 test_email_connection: One-click test of SMTP / IMAP connection

• 🚀 Two transport methods: stdio (local debugging) / SSE (cloud remote deployment)

• 🔐 Endpoint Bearer Token authentication, all credentials go through environment variables, never hardcoded

Architecture

┌──────────────┐   HTTPS + Bearer   ┌──────────────────┐   SMTP/IMAP   ┌──────────────┐
│ WorkBuddy    │ ─────────────────▶ │ ai-mail-mcp      │ ────────────▶ │ 你的域名邮箱   │
│ 桌面端 / 移动端 │                   │ (云端 MCP Server) │               │ you@your.com │
└──────────────┘                   └──────────────────┘               └──────────────┘

Cloud deployment is key: one HTTPS endpoint that both desktop and mobile can connect to, no need for the local machine to be on.

Quick Start

1. Configure Environment Variables

cp .env.example .env
# 编辑 .env，填入你的邮箱账号、授权码、SMTP/IMAP 地址、Bearer Token

2A. Local Debugging (stdio)

npm install
MCP_TRANSPORT=stdio node server.js

2B. Cloud Deployment (SSE, Recommended)

Requires a server with a public IP + a domain name (HTTPS).

cp .env.example .env   # 在服务器上填写真实配置
docker compose up -d

Then use nginx reverse proxy + acme.sh/certbot to sign an HTTPS certificate (there are commented examples in docker-compose.yml), resulting in an endpoint like https://mcp.your-domain.com/mail-mcp/sse.

3. Connect to WorkBuddy (Custom Connector)

Edit ~/.workbuddy/mcp.json:

{
  "mcpServers": {
    "ai-mail-mcp": {
      "type": "sse",
      "url": "https://mcp.your-domain.com/mail-mcp/sse",
      "headers": {
        "Authorization": "Bearer 你的随机Token"
      }
    }
  }
}

In the WorkBuddy connector management page, click Trust / Enable on this connector and restart the session. You can then use in conversations:

• "Send an email to xx, subject…, body…"

• "Check my emails from the last 3 days and summarize which ones need replies"

• "Every morning at 9, send a summary of yesterday's emails to my inbox"

Tool List

Security Tips

• MCP_BEARER_TOKEN must be set to a sufficiently random long string (generated with openssl rand -hex 32) and kept securely

• Do not commit .env or real credentials to any repository; only .env.example is committed to this documentation repository

• It is recommended to use a separate email account with minimal permissions (send/receive only, no delete/management permissions)

• Self-hosting means all email data stays on your own server and is not handed over to third parties

License

MIT