Yahoo Mail MCP Server

一个用于通过 IMAP 为 Yahoo Mail 提供完整邮件管理的模型上下文协议（MCP）服务器。该服务器支持本地 stdio 传输（用于 Claude Desktop）和 HTTP/SSE 传输（用于通过 Claude.ai 进行远程访问）。

功能

• 安全的 OAuth 2.0 认证：使用带 PKCE 的 OAuth 2.0 授权码流程保护您的远程 MCP 服务器

• 基于 UID 的操作：使用删除邮件后不会改变的永久性 IMAP UID（v3.0.0+）

• 完整的邮件管理：提供批量处理支持和完整邮件操作

• 十一大实用工具：

  • list_emails：列出最新邮件及增强元数据（大小、标志、附件）并支持分页

  • read_emails：读取邮件完整内容（支持批量）

  • search_emails：高级搜索并带过滤（日期范围、发件人、未读取状态）

  • list_folders：发现所有可用的 IMAP 文件夹

  • delete_emails：将邮件移至回收站（软删除，可恢复）

  • archive_emails：将邮件归档以便长期存储

  • mark_as_read：将邮件标记为已读

  • mark_as_unread：将邮件标记为未读

  • flag_emails：标记邮件为重要/加星

  • unflag_emails：删除邮件标记

  • move_emails：将邮件移动至任意文件夹

• 丰富元数据：所有邮件条目均包含 UID、大小、标记、hasAttachments 和文件夹信息

• 高级搜索：支持按日期范围、发送者、未读状态进行过滤，并可任意文件夹搜索

• 批量操作：所有管理操作均支持一次处理多封邮件，并跟踪准确的成功/失败情况

• 双传输模式：

  • stdio：用于本地 桌面集成

  • sse：用于通过 HTTP/Server-Sent Events（服务器发送事件）远程访问（Render.com 必需）

• 跨平台：可平台开发环境运行

• Docker 支持：使用 Docker 和 Docker 集群进行容器化部署

• 云原生：可配置为带 OAuth 安全的简单部署到 Render.com

Related MCP server: Yahoo Mail MCP Server

前置要求

本地开发准备

• Node.js：版本 18.0.0 或更高

• Yahoo Mail 账户：启用应用专用密码

• Git：用于版本控制

Docker 开发/部署

• Docker：最新版本

• Docker Compose：最新版本（Windows/Mac 上的 Docker Desktop 已包含）

用于 Render.com 部署

• GitHub 账户：用于托管您的仓库

• Render.com 账户：免费在线可获取于 https://render.com

快速开始

1. 克隆并设置

# Clone the repository
git clone <your-repo-url>
cd yahoo-mail-mcp-server

# Copy environment template
cp .env.example .env

2. 获取 Yahoo Mail 应用专用密码

1. 转到 https://login.yahoo.com/account/security/security/security

2. 点击"生成应用密码或"管理应用密码"

3. 选择"其他应用"并输入"MCP Server"

4. 复制生成的 16 位密码

3. 配置环境变量

使用您的凭据编辑 .env 文件：

YAHOO_EMAIL=your.email@yahoo.com
YAHOO_APP_PASSWORD=your16charpassword
TRANSPORT_MODE=stdio  # or 'sse' for HTTP mode
PORT=3000

4. 安装依赖项

** Windows (PowerShell)：**

npm install

Linux/macOS (Bash)：

npm install

5. 在本地运行

Stdio 模式下（用于 C型桌面）：

npm run start:stdio

SSE 模式（用于测试 HTTP 端点）：

npm run start:sse

开发模式（启用自动重载）：

npm run dev

Docker 用法

使用 Docker 构建和运行

Windows (PowerShell)：

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

Linux/macOS (Bash)：

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

手动 Docker 命令

Windows (PowerShell)：

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 `
  -e YAHOO_EMAIL=your.email@yahoo.com `
  -e YAHOO_APP_PASSWORD=yourpassword `
  -e TRANSPORT_MODE=sse `
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

Linux/macOS (Bash)：

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 \
  -e YAHOO_EMAIL=your.email@yahoo.com \
  -e YAHOO_APP_PASSWORD=yourpassword \
  -e TRANSPORT_MODE=sse \
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

测试服务器

测试健康检查端点

Windows (PowerShell)：

# Using npm script
npm run test:health

# Using curl (if installed)
curl http://localhost:3000/health

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/health | Select-Object -Expand Content

Linux/macOS (Bash)：

# Using npm script
npm run test:health

# Using curl
curl http://localhost:3000/health

测试 SSE 端点

Windows (PowerShell)：

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/mcp/sse

Linux/macOS (Bash)：

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

部署到 Render.com

步骤 1：准备您的仓库

** Windows (PowerShell)：**

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

Linux/macOS (Bash)：

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

步骤 2：部署到 Render

1. 注册/登录 Render.com

• 转到 https://render.com

• 点击"Get Started for Free"或"Login"

2. 连接 GitHub 仓库

• 点击右上角的"New +"按钮

• 选择"Web Service"

• 点击"Connect GitHub"并授权 Render

• 选择您的 yahoo-mail-mcp-server 仓库

3. 配置服务

• 名称：yahoo-mail-mcp-server（或您喜欢的名称）

• Runtime：Docker

• 区域：选择离您最近的区域（Oregon、Frankfurt、Singapore、Oio）

• 分支：main

• 计划：Free（生产用 Starter）

4. 设置环境变量

在 "Environment" 部分中，点击 "Add Environment Variable" 并添加：

重要：

将 YAHOO_EMAIL、YAHOO_APP_密码、OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET 标记为"Secret"

• PORT 由 Render 自动设置，不要手动添加

• 保存 OAuth 凭据 - 配置桌面时需要它们

5. 部署

• 点击"Create Web Service"

• Render 将自动构建和部署您的 Docker 容器

• 等待部署完成（首次构建需要 5-10 分钟）

6. 获取您的服务 URL

• 部署完成后，您会获得一个像这样的 URL：https://yahoo-mail-mcp-server.onrender.com

• 通过访问 https://yahoo-mail-mcp-server.onrender.com/health 测试

步骤 3：连接到 Claude Desktop

注意：远程 MCP 服务器需要 Claude Pro、Max、Team 或 Enterprise 计划。

1. **打开 Claude Desktop **

• 启动您电脑上的 Claude Desktop 应用

2. 添加 MCP 连接器

• 点击您的个人资料头像或菜单

• 选择"设置"

• 转到"Connectors"部分

• 点击"Add Custom 连接器"

3. 配置连接器

• 名称：Yahoo Mail

• URL：https://your-service-name.onrender.com/mcp/sse

示例：

https://yahoo-mail-mcp-server.onrender.com/mcp/sse

4. 配置 OAuth 认证

• 点击 "Advanced Settings" ⚙️

• 输入步骤 4 中的 OAuth 凭据：

• OAuth Client ID：OAUTH_CLIENT_ID 环境变量的值

• OAuth Client Secret：OAUTH_CLIENT_SECRET 环境变量的值

5. 保存并测试

• 点击"添加"或"保存"

• Claude Desktop 将使用 OAuth 2.0 进行身份验证

• 如果成功，您将看到连接器处于活动状态

• 现在您即可在对话中使用 Yahoo Mail 工具！

步骤 4：在 Claude.ai 中连接使用 MCP 服务器

连接后，您会在对话中使用这些工具：

Can you list my recent emails?

Can you read email number 5?

Can you search for emails from john@example.com?

故障排除

常见问题

1. "Authentication failed" 错误

解决方案：验证应用专用密码

• 确保使用的是应用专用密码，而不是该有的 Yahoo 密码

• 在 https://login.yahoo.com/account/security 生成新的应用专用密码

• 检查 .env 文件或 Render 环境变量是否有拼写错误

2. Docker 构建在 Windows 上失败

解决方案：检查 Docker Desktop 设置

• 确保 Docker Desktop 正在运行

• 检查是否启用了 WSL2（设置 > 常规 > 使用 WSL2 based engine）

• 确认文件共享已启用（设置 > 资源 > 文件共享）

3. 端口 3000 已被占用

解决方案：更改端口

Windows (PowerShell)：

$env:PORT=3001; npm run start:sse

Linux/macOS (Bash)：

PORT=3001 npm run start:sse

或编辑 .env：

PORT=3001

4. Render 部署失败

解决方案：查看日志

• 转到 Render 仪表板

• 点击您的服务

• 单击"Logs"标签

• 查找错误消息

• 常见问题：

  • 缺少环境变量

  • Dockerfile 路径不正确

  • 构建超时（在设置中增加构建超时时间）

5. SSE 连接断开

解决方案：Render 免费流量限制

• 免费层服务在闲置 15 分钟后休眠

• 休眠后的首次请求需要 30-60 秒才能唤醒

• 升级到 Starter 计划（每月 7 美元）始终在线服务

6. IMAP 连接超时

解决方案：检查 Yahoo Mail IMAP 设置

• 确保 Yahoo Mail 设置中已启用 IMAP

• 前往 Yahoo Mail > 设置 > 更多设置 > 邮箱

• 确认允许 IMAP 访问

• 检查防火墙设置未阻挡端口 993

Windows 特定问题

行尾问题

如果您看到关于行尾的错误：

Windows (PowerShell)：

# Configure git to handle line endings correctly
git config --global core.autocrlf input

# Re-clone the repository
git clone <your-repo-url>

npm 脚本不起作用

如果跨平台脚本失败：

Windows (PowerShell)：

# Install cross-env globally
npm install -g cross-env

# Or run scripts directly
node server.js

Linux 特定问题

Docker 权限错误

Bash

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again, or run:
newgrp docker

# Test
docker ps

环境变量参考

注意：OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET 仅远程部署（Render.com）时需要。本地 stdio 模式不需要 OAuth。

可用的 npm 脚本

项目结构

yahoo-mail-mcp-server/
├── server.js                 # Main server code
├── package.json             # Node.js dependencies and scripts
├── Dockerfile               # Docker build configuration
├── docker-compose.yml       # Docker Compose configuration
├── render.yaml              # Render.com deployment config
├── .env.example             # Environment variable template
├── .env                     # Your local environment variables (gitignored)
├── .dockerignore            # Files to exclude from Docker build
├── .gitignore               # Files to exclude from git
├── .gitattributes           # Git line ending configuration
└── README.md                # This file

安全最佳实践

1. OAuth 2.0 保护（远程部署）

   • 服务器要求所有 MCP 请求都必须经过 OAuth 2.0 认证

   • 使用带 PKCE 的授权码流程（Proof of Key for Code Exchange）

   • 只有凭据正确的客户端才能访问你的邮件

   • 生成强随机凭据：openssl rand -hex 16 和 openssl rand -hex 32

   • 将凭据安全地存储在 Render 仪表板中（标记为 "Secret"）

2. 切勿提交凭据

   • .env 文件已被 gitignore 忽略

   • 始终使用 .env.example 作为模板

   • 在 Render 仪表板中设置敏感值

   • 切勿公开分享 OAuth 凭据

3. 使用应用专用密码

   • 绝不要使用主 Yahoo 密码

   • 为每个服务生成新密码

   • 定期撤销未使用的密码

   • 应用密码可以在不更改主密码的情况下被撤销

4. 邮件管理操作

   • 所有修改操作都是可逆的（软删除，而非永久删除）

   • 已删除的邮件会移至回收站（免费账户 2.0.7 天内可恢复）

   • 归档、标记和读取状态更改都是非破坏性感

   • 移动操作会保留动邮件内容和元数据

   • 有无无发送操作——服务器不能代表你发送邮件

5. 生产环境中的 HTTPS

   • Render.com 提供免费 SSL 证书

   • 所有传输内容都经过加密（TLS/SSL）

   • IMAP 连接使用 TLS

   • OAuth 令牌在传输中安全加密

开发工作流

进行改改

Windows（PowerShell）：

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

Linux/macOS（Bash）：

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

查看日志

本地开发：

# The server logs to stderr
npm run start:sse

Docker：

npm run docker:compose:logs

Render.com：

• 前往你的服务仪表板

• 点击 "Logs" 标签

• 实时日志会显示在这里

API 端点

在以 SSE 模式运行时，服务器会暴露以下端点：

0 健康检查响应示例

{
  "status": "ok",
  "service": "yahoo-mail-mcp",
  "version": "1.0.0",
  "timestamp": "2025-01-11T12:34:56.789Z"
}

破坏性变更与迁移指南

️ v3.0.0 破坏性变更

3.0.0 版本引入了基于 UID 操作，这从根本上改变了你与邮件的交互方式。这是一个破坏性变更，需要你更新代码。

变更内容

• 1. 参数重命名：sequenceNumbers → uids

所有邮件管理工具现在使用 uids（永久性标识符）而不是 sequenceNumbers（临时性位置）：

// ❌ v2.x (OLD - sequence numbers)
read_email({ sequenceNumbers: [1, 2, 3] })
delete_emails({ sequenceNumbers: [5] })

// ✅ v3.0.0 (NEW - UIDs)
read_email({ uids: [510867, 510866, 510862] })
delete_emails({ uids: [510867] })

• 2. 响应格式：明文 → JSON

所有工具现在返回结构化 JSON 而不是明文：

// ❌ v2.x response
"Email 1 of 10..."

// ✅ v3.0.0 response
{
  "emails": [...],
  "totalCount": 10,
  "returned": 10
}

• 3. 新的必需工作流

现在，你必须先通过 list_emails 或 search_emails 获取 UID，然后再执行所有操作：

// Step 1: Get UIDs
const result = list_emails({ count: 10 });
// Returns: { emails: [{ uid: 510867, ... }, { uid: 510866, ... }] }

// Step 2: Use UIDs for operations
const uidsToDelete = [510867, 510866];
delete_emails({ uids: uidsToDelete });

为什么 UID 更好

序列号（v2.x.x）：

• ❌ 在邮件删除时会发生变化

• ❌ 基于位置（邮件 #1、#2、#3）

• ❌ 在操作期间可能失效

• ❌ 导致混乱和错误

UIDs（v3.0.0）：

• ✅ IMAP 服务器分配的永久标识符

• ✅ 即使其他邮件被删除也不会改变

• ✅ 在邮件被永久删除之前一直有效

• ✅ 适用于批量操作

️⃣ 迁移清单

• 更新所有 sequenceNumbers 调用，改为使用 uids

• 更新代码，先从 list_emails 或 search_emails 获取 UID

• 更新代码，使其处理 JSON 响应而不是明文

• 测试批量操作，确保所有 UID 都被处理（v3.0.0 修复了关键性的批量操作 bug）

• 了解新功能：分页、元数据、高级搜索、文件夹支持

v3.0.0 新增功能

1. 丰富元数据：所有邮件均包含 uid、size、flags、hasAttachments

2. 分页：list_emails 支持 offset 和 limit 参数

3. 高级搜索：search_emails 支持日期范围、发件人筛选、仅未读

4. 文件夹支持：所有工具支持 folder 参数（默认：INBOX）

5. list_folders：发现可用 IMAP 文件夹的新工具

6. 准确的批量操作：修复了关键 bug，原问题会导致仅处理第一个 UID

7. 增强的错误处理：更佳的超时和连接错误信息

MCP 工具

list_emails

列出带丰富元数据（UID、大小、标志、附件）和分页支持的近期邮件。

参数：

• count（可选）：要获取的邮件数（默认10，最大50）

• folder（可选）：列出的文件夹（默认 'INBOX'）。用 list_folders 查看可用的文件夹

• offset（可选）：分页时跳过的邮件数（默认0）

响应： 包含 emails 数组的 JSON，每封邮件包含以下元数据：

• uid：永久 IMAP UID（所有操作均使用此值）

• sequenceNumber：文件中的位置（仅参考，不使用）

• from：发件地址

• subject：邮件主题

• date：RFC 2822 格式日期

• size：字节数

• flags：IMAP 标志数组（例如 ['\\Seen']、['\\Flagged']

• hasAttachments：布尔值，指示邮件是否有附件

示例：

// List 20 most recent emails
list_emails({ count: 20 })

// List emails with pagination (skip first 10)
list_emails({ count: 10, offset: 10 })

// List emails from Sent folder
list_emails({ count: 15, folder: "Sent" })

read_email

使用 UIDs 读取完整邮件内容（支持批量读取）。

参数：

• uids（必填）：要读取的 UID 数组（从 list_emails 或 search_emails 获取）

• folder（可选）：邮件所在文件夹（默认：'INBOX'）

响应： 包含详细邮件数据（含正文）的 JSON

示例：

// Read a single email
read_email({ uids: [510867] })

// Read multiple emails
read_email({ uids: [510867, 510866, 510862] })

// Read email from Sent folder
read_email({ uids: [510867], folder: "Sent" })

search_emails

高级搜索，支持日期范围、发件人和未读状态等条件。

参数：*

• query（可选）：主题或发件人的搜索词（可留空，用于仅按日期搜索）

• count（可选）：返回结果数（默认：10，最大：50）

• dateFrom（可选）：筛选此日期之后的邮件（ISO 8601 / RFC 2822 格式）

• dateTo（可选）：筛选此日期之前的邮件（ISO 8601 / RFC 2822 格式）

• sender（可选）：按某个发件人地址邮件名或名称过滤

• unreadOnly（可选）：仅返回未读邮件（默认：false）

• folder（可选）：要搜索的文件夹（默认：'INBOX'）

响应： JSON 包含 emails 数组、totalMatches、returned、query、filters 和 folder

示例：

// Basic search
search_emails({ query: "invoice", count: 15 })

// Search unread emails only
search_emails({ query: "meeting", unreadOnly: true })

// Search by date range
search_emails({ dateFrom: "2025-01-01", dateTo: "2025-01-31" })

// Search by sender
search_emails({ sender: "boss@company.com" })

// Combined filters
search_emails({
  query: "report",
  sender: "team@company.com",
  dateFrom: "2025-01-15",
  unreadOnly: true
})

list_folders

发现你 Yahoo Mail 账户中所有可用的 IMAP 文件夹。

参数： 无

响应： JSON 包含文件夹对象数组，每个对象含 name、path、delimiter 和 children

示例：

// List all folders
list_folders()

// Example response:
// {
//   "folders": [
//     { "name": "INBOX", "path": "INBOX" },
//     { "name": "Sent", "path": "Sent" },
//     { "name": "Trash", "path": "Trash" },
//     { "name": "Archive", "path": "Archive" }
//   ]
// }

delete_email

使用 UID 将邮件移至垃圾箱文件夹（软删除 - 可恢复）。

参数：

• uids（必填）：要删除的 UID 数组（vialist_emails 或 search_emails 获取）

• folder（可选）：源文件夹（默认：'INBOX'）

响应： 成功/失败消息，含已处理邮件的准确数量

示例：

// Delete a single email
delete_emails({ uids: [510867] })

// Delete multiple emails
delete_emails({ uids: [510867, 510866, 510862, 510856] })

// Delete from Sent folder
delete_emails({ uids: [510867], folder: "Sent" })

archive_emails

使用 UID 将邮件移至归档文件夹以便长期存储。

参数：

• uids（必填）：要归档的 UID 数组

• folder（可选）：源文件夹（默认：'INBOX'）

响应： 成功/失败消息，含已处理邮件的准确数量

示例：

// Archive a single email
archive_emails({ uids: [510867] })

// Archive multiple emails
archive_emails({ uids: [510867, 510866, 510862, 510851] })

mark_as_read

使用 UID 将邮件标记为已读，通过添加 Seeen 标志实现。

参数：

• uids（必填）：要标记为已读的 UID 数组 ::Пsmntn: etc.

Actually ensure correct closure. We'll continue.

• folder（可选）：邮件所在文件夹（默认：'INBOX'）

响应： 成功/失败消息，含被处理邮件的数量

示例：

// Mark a single email as read
mark_as_read({ uids: [510867] })

// Mark multiple emails as read
mark_as_read({ uids: [510867, 510866, 510862, 510851, 510865] })

mark_as_unread

使用 UID 将邮件标记为未读，通过移除 Seen 标志实现。

参数：

• uids（必填）：要标记为未读的 UID 数组

• folder（可选）：邮件所在文件夹（默认：'INBOX'）

响应： 成功/失败消息，含被处理邮件的数量

示例：

// Mark a single email as unread
mark_as_unread({ uids: [510867] })

// Mark multiple emails as unread
mark_as_unread({ uids: [510869, 510867, 510866] })

flag_emails

使用 UID 将邮件标记为重要/星级，通过添加 Flagged 标志实现。

参数：

• uids（必填）：要标记的 UID 数组

• folder（可选）：邮件所在文件夹（默认：'INBOX'）

响应： 成功/失败消息，含被处理邮件的数量

示例：

// Flag a single email
flag_emails({ uids: [510867] })

// Flag multiple emails
flag_emails({ uids: [510851, 510865, 510864] })

unflag_emails

使用 UID 移除邮件的重要/星标标记，通过移除 Flagged 标志实现。

参数：

• uids（必填）：要取消标记的 UID 数组

• folder（可选）：邮件所在文件夹（默认：'INBOX'）

响应： 成功/失败消息，含被处理邮件的数量

示例：

// Unflag a single email
unflag_emails({ uids: [510867] })

// Unflag multiple emails
unflag_emails({ uids: [510867, 510866, 510862] })

move_emails

使用 UID 将邮件移动到指定文件夹。

参数：

• uids（必填）：要移动的 UID 数组

• folderName（必填）：目标文件夹名称（例如 "Work"门、"Personal"、"Archive"）

• sourceFolder（可选）：源文件夹（默认：'INBOX'）

响应： 成功/失败消息，含被处理邮件的数量

示例：

// Move a single email to Work folder
move_emails({ uids: [510867], folderName: "Work" })

// Move multiple emails to Personal folder
move_emails({ uids: [510867, 510866, 510862], folderName: "Personal" })

// Move from Sent to Archive
move_emails({ uids: [510867], folderName: "Archive", sourceFolder: "Sent" })

性能考虑

Render.com 免费层

• 无活动后休眠：服务在 15 分钟无请求后进入休眠

• 唤醒时间：第一个请求需要 30-60 秒

• 每月小时数：每月 750 小时（足够中等使用）

• 升级：Starter 计划 $7/月（始终在线）

IMAP 性能

• 连接池：每个请求都会创建新的 IMAP 连接

• 超时：连接和认证超时为 30 秒

• 限流：Yahoo 可能会对过多请求限流

• 建议：尽可能在客户端缓存结果

跨平台兼容性

该项目设计为可在以下平台上无缝运行：

• Windows 10/11，支持 PowerShell 或命令提示符

• Linux（Ubuntu、Debian、Fedora 等）

• macOS（Intel 及 Apple Silicon）

• Docker Desktop（Windows、Mac、Linux）

• WSL2（Windows Subsystem for Linux）

行结尾

• .gitattributes 确保仓库代码使用 LF 行结束符

• 在 Windows（CRLF）和 Linux（LF）下正常工作

• Linux 在容器内使用 LF

路径处理

• 代码中所有路径均使用正斜杠

• 使用 path.join() 处理跨平台兼容

• 支持 Windows 反斜杠和 Unix 正斜杠

贡献

1. 重新分仓库

2. 创建功能分支：git checkout -b feature-name

3. 进行你的修改

4. 尽量在 Windows 和 Linux 上都测试

5. 提交：git commit -am "Add feature"

6. 推送：git push origin feature-name

7. 创建 Pull Requests

许可证

MIT License

支持

• Issues： 在 https://github.com/yourusername/yahoo-mail-mc-server/issues 报告问题

• Discussions： 在 GitHub Discussions 中提问

• MCP 文档：https://modelcontextprotocol.io

变更日志

v3.0.0（2025-01-08） - UID 迁移

重大变更

• 现在所有工具使用 uids 参数，而不是 sequenceNumbers

• 响应格式从普通文本改为结构化的 JSON

• uids 是永久标识，邮件删除后不会改变

新增功能：

• 增强的元数据：所有电子邮件均包含 uid、size、flags、hasAttachments

• 分页支持：list_emails 接受 offset 和 limit 参数

• 高级搜索筛选：dateFrom、dateTo、sender、unreadOnly 参数

• 文件夹支持：所有工具均接受 folder 参数（默认：INBOX）

• 新工具：list_folders 用于发现可用的 IMAP 文件夹

• 增强的错误处理：改进的超时和连接错误消息，带 Render 休眠检测

错误修复：

• CRITICAL：修复了批量操作中只处理第一个 UID 的错误

• 所有批量操作现在都能准确处理数组中的每个 UID

• 成功/失败消息现在会报告已处理邮件的准确数量

迁移指南：

• 将所有工具调用中的 sequenceNumbers 替换为 uids

• 从 list_emails 或 search_emails 的响应中获取 UID

• 更新代码以处理 JSON 响应，而不是纯文本

• 详见上文的 "Breaking Changes & Migration Guide" 部分

v2.0.1 (2025-01-17)

• 修复：增强了所有邮件操作的输入验证

• 新增共享验证辅助函数，避免无效序号导致 IMAP 错误

• 改进错误消息，便于调试

v2.0.0 (2025-01-16)

• 破坏性变更：read_email 现在使用 sequenceNumbers（数组）而不是 sequenceNumber（单个数字）

• 新增完整邮件管理功能，支持批量操作

• 七个新工具：delete_emails、archive_emails、mark_as_read、mark_as_unread、flag_emails、unflag_emails、move_emails

• 所有修改操作均支持批量处理

• 通过可逆操作增强安全性（软删除，不永久删除）

v1.0.0 (2025-01-11)

• 首次发布

• 支持 stdio 和 SSE 传输

• 支持 Docker 和 Docker Compose

• Render.com 部署配置

• 跨平台兼容（Windows/Linux）

• 三个核心工具：list_emails、read_email、search_emails

致谢

• 基于 @modelcontextprotocol/sdk 构建

• 使用 imap 进行 IMAP 访问

• 使用 mailparser 解析邮件

• 部署于 Render.com

常见问题

问：我可以将其用于 Gmail 或其他电子邮件提供商吗？

答：目前，此服务器针对 Yahoo Mail 进行配置。如需支持其他提供商，您需要修改 server.js（第 166-179 行）中的 IMAP 配置。

问：将其用于我的电子邮件账户安全吗？

答：安全！服务器使用应用专用密码（而非您的主密码），且所有修改操作均可逆。删除操作会将邮件移至回收站（可恢复），服务器绝不会永久删除邮件，也绝不会代您发送邮件。

问：在 Render 上运行的费用是多少？

答：免费层级每月提供 750 小时，足以满足中等使用；如需常驻服务，Starter 计划为每月 7 美元。

问：我可以在其他云平台上运行吗？

答：可以！Docker 配置适用于任何支持 Docker 容器的平台（AWS ECS、Google Cloud Run、Azure 容器实例、Heroku、Fly.io 等）。

问：我需要保持电脑开机运行吗？

答：不需要！部署到 Render.com（或其他云平台）后，服务器会在云端独立运行。

问：部署后如何更新服务器？

答：只需将更改推送到 GitHub。Render 会自动检测推送并重新部署服务。

问：多人可以共用同一个已部署的服务器吗？

答：服务器仅连接一个 Yahoo Mail 账户（环境变量中配置的账户）。如果每个用户需要自己的邮箱账户，就需要各自部署一份。

问：如果我忘记应用专用密码怎么办？

答：您可以在 https://login.yahoo.com/account/security/app-passwords 生成一个新密码，并在 Render 环境变量（Settings > Environment）中更新。

后续步骤

部署成功后：

1. ✅ 测试健康检查端点

2. ✅ 连接 Claude.ai

3. ✅ 尝试列出邮件

4. ✅ 阅读几封邮件

5. ✅ 搜索收件箱

6. 🎉 尽情享受您的 Yahoo Mail MCP 服务器！

Happy Coding！ 如果您有任何问题或疑问，请在 GitHub 上提出 issue。