MCP Server Mail Agent

MCP电子邮件服务器

A. 模型上下文协议（MCP）服务器 用于通过统一收件箱支持多个提供商和帐户的电子邮件管理。

特性

• 多供应商：Gmail（OAuth2）、Outlook（Microsoft Graph）和任何IMAP服务器
• 多账户：跨所有电子邮件帐户的统一收件箱
• 安全第一：机密必须使用环境变量（明文被拒绝）
• Docker就绪：在容器中运行，以确保安全性和可移植性
• MCP标准：适用于Claude Code、Claude Desktop和任何兼容MCP的客户端

支持的提供商

快速开始

1.克隆和安装

git clone https://github.com/gufao/mcp-server-mail-agent.git
cd mcp-server-mail-agent
npm install

2.配置

# Create credentials directory
mkdir -p credentials

# Copy example files
cp accounts.example.json credentials/accounts.json
cp .env.example .env

# Edit with your settings
nano credentials/accounts.json
nano .env

3.设置提供者

IMAP（最简单-适用于任何电子邮件）

编辑 .env:

IMAP_HOST=imap.gmail.com
IMAP_USER=your@gmail.com
IMAP_PASSWORD=your-app-password
SMTP_HOST=smtp.gmail.com

编辑 credentials/accounts.json:

{
  "accounts": [
    {
      "id": "main",
      "name": "My Email",
      "provider": "imap",
      "default": true,
      "config": {
        "host": "${IMAP_HOST}",
        "port": 993,
        "user": "${IMAP_USER}",
        "password": "${IMAP_PASSWORD}",
        "tls": true,
        "smtpHost": "${SMTP_HOST}",
        "smtpPort": 587,
        "smtpSecure": false
      }
    }
  ]
}

Gmail（OAuth2）

1. 首选 谷歌云控制台
2. 创建项目，启用Gmail API
3. 创建OAuth凭据（桌面应用程序）
4. 下载为 credentials/gmail-credentials.json
5. 运行： npm run auth:gmail

Outlook（OAuth2）

1. 首选 Azure 门户 >应用程序注册
2. 新注册>设置重定向URI： http://localhost:3000/callback
3. 添加API权限： Mail.Read, Mail.Send, Mail.ReadWrite, offline_access
4. 创建客户端密钥
5. 设置环境变量并运行： npm run auth:outlook

4.构建和测试

# Build
npm run build

# Test locally
source .env && ACCOUNTS_PATH=./credentials/accounts.json node dist/index.js

# Build Docker
docker build -t mcp-email-server .

# Test Docker
docker run --rm -v "$(pwd)/credentials:/app/credentials:ro" --env-file .env mcp-email-server

5.添加到Docker MCP网关

增添 ~/.docker/mcp/catalogs/custom.yaml:

  email:
    description: "Multi-account Email MCP Server supporting IMAP, Gmail, and Outlook"
    title: "Email Manager"
    type: server
    dateAdded: "2025-11-23T00:00:00Z"
    image: mcp-email-server:latest
    ref: ""
    tools:
      - name: list_accounts
      - name: fetch_unread_emails
      - name: search_emails
      - name: get_email
      - name: mark_as_read
      - name: mark_as_unread
      - name: send_email
      - name: get_all_folders
      - name: delete_email
    prompts: 0
    resources: {}
    volumes:
      - "/path/to/credentials:/app/credentials:ro"
    env:
      - name: ACCOUNTS_PATH
        value: "/app/credentials/accounts.json"
      - name: IMAP_HOST
        value: "your-imap-server.com"
      - name: IMAP_USER
        value: "your-email@example.com"
      - name: IMAP_PASSWORD
        value: "your-app-password"
      - name: SMTP_HOST
        value: "your-smtp-server.com"
    metadata:
      category: productivity
      tags:
        - email
        - imap
        - gmail
        - outlook
      license: GPL-3.0
      owner: local

重要提示： 这 env 字段必须是数组 {name, value} 物体。Docker MCP网关不支持 ${VAR} 环境变量的语法-您必须直接在目录文件中提供实际值。

增添 ~/.docker/mcp/registry.yaml:

registry:
  email:
    ref: ""

然后运行 /mcp 在Claude Code中重新连接或重新启动Claude Desktop。

可用工具

安全

强制安全

• 明文机密被拒绝：如果发生以下情况，服务器将拒绝启动 password 或 clientSecret 硬编码在 accounts.json
• 需要环境变量：所有秘密都必须使用 ${VAR_NAME} 语法
• 启动验证：报告丢失或空的秘密

最佳实践

• 永不承诺 .env 或 credentials/ 到git（已经在 .gitignore)
• 使用应用程序密码而不是IMAP的常规密码
• Docker卷以只读方式挂载
• 容器以非root用户身份运行

常见IMAP服务器

使用示例

"What email accounts do I have?"
"Show me my unread emails"
"Search for emails from john@example.com"
"Read email ID abc123 from my work account"
"Send an email to jane@example.com about the meeting"
"Mark that email as read"
"Delete the spam email"

项目结构

mcp-email-server/
├── src/
│   ├── index.ts              # MCP server entry
│   ├── types.ts              # TypeScript interfaces
│   ├── config.ts             # Environment configuration
│   ├── account-manager.ts    # Multi-account orchestration
│   ├── providers/
│   │   ├── base.ts           # Abstract EmailProvider
│   │   ├── gmail.ts          # Gmail API
│   │   ├── outlook.ts        # Microsoft Graph
│   │   ├── imap.ts           # IMAP/SMTP
│   │   └── index.ts          # Provider factory
│   └── auth/
│       ├── gmail-auth.ts     # Gmail OAuth setup
│       └── outlook-auth.ts   # Outlook OAuth setup
├── credentials/              # Your credentials (gitignored)
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json

发展

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Auth scripts
npm run auth:gmail
npm run auth:outlook

故障排除

许可证

GPL-3.0许可证-请参阅 许可证 了解详情。

作者

奥古斯托·林哈雷斯 - 18X实验室

______________________________________________________________________

与 模型上下文协议