yahoo-mail-mcp

yahoo-mail-mcp

通过 Claude 读取、搜索、整理和清理 Yahoo Mail 邮箱账户——使用普通 IMAP，无需 Yahoo API 密钥。

一个 MCP（Model Context Protocol）服务，可让大模型通过 IMAP 读取、搜索、移动和删除 Yahoo Mail 邮箱中的邮件。

提供的工具：list_folders、create_folder、list_emails、search_emails、 read_email、get_attachment、move_email、delete_email、mark_email。

每个工具都会打开一个短时 IMAP 连接，完成操作后将其关闭。 默认情况下，删除操作会将邮件移至 Trash（通过 IMAP 特殊用途标志查找，而非使用硬编码名称）——只有调用方明确传入 permanent=True，才会永久删除。没有任何工具能删除或清空整个文件夹；只能按 UID 操作单封邮件。

1. 在 Yahoo 账户中启用 IMAP

大多数 Yahoo Mail 账户默认已启用 IMAP 访问。如果邮件客户端无法连接，请检查：Yahoo Mail → Settings → More Settings → Mailboxes → [您的账户] → "Allow apps that use less secure sign in" 并非此处所需的设置——它适用于旧版密码验证。现代 Yahoo 要求使用应用密码（见下文），无论是否启用该旧版开关，都可以正常使用。如果仍然遇到连接问题，请登录 Yahoo Account Security，确认账户未被锁定或标记为存在可疑活动。

2. 生成 Yahoo 应用密码

启用两步验证后，Yahoo 会阻止使用普通账户密码登录 IMAP（并且通常也建议使用应用密码）。生成方法如下：

1. 前往 https://login.yahoo.com/account/security。
2. 如果尚未启用，请开启两步验证（应用密码必需）。
3. 找到 "Generate app password"（有时位于 "App passwords" / "Manage app passwords" 下）。
4. 选择 "Other app"，为其取名，例如 yahoo-mail-mcp，然后生成密码。
5. 复制生成的密码（通常为 16 个字符，不含空格）——Yahoo 只会显示一次。

将此应用密码用作 YAHOO_APP_PASSWORD，切勿使用您的真实账户密码。

3. 安装依赖项

需要 Python 3.10+。

cd yahoo-mail-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. 配置凭据

cp .env.example .env

编辑 .env 并填写：

[email protected]
YAHOO_APP_PASSWORD=your16charapppassword

.env 已列入 .gitignore——切勿提交。

5. 检查连接是否正常

将服务接入 Claude 之前，请确认凭据有效：

python test_connection.py

此操作会登录、列出您的文件夹，并打印收件箱中最新的 3 封邮件。 绝不会打印您的应用密码。

6. 运行服务

python server.py

此服务通过 stdio 使用 MCP 通信——它旨在由 MCP 客户端（Claude Desktop、Claude Code）启动，而非作为交互式程序独立运行。

7. 在 Claude Desktop / Claude Code 中注册

在 MCP 配置中添加条目，指向此项目虚拟环境中的 Python 和 server.py。请使用绝对路径。

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "yahoo-mail": {
      "command": "/absolute/path/to/yahoo-mail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/yahoo-mail-mcp/server.py"],
      "env": {
        "YAHOO_EMAIL": "[email protected]",
        "YAHOO_APP_PASSWORD": "your16charapppassword"
      }
    }
  }
}

Claude Code——通过 CLI 添加相同的服务：

claude mcp add yahoo-mail /absolute/path/to/yahoo-mail-mcp/.venv/bin/python /absolute/path/to/yahoo-mail-mcp/server.py

或者，按照与上述相同的 JSON 结构，直接将其添加到 Claude Code MCP 配置文件中。

如果您不想将应用密码写入 MCP 配置的 env 块中，可以省略该块，并改为使用 server.py 所在目录中的 .env——服务会通过 python-dotenv 自动加载它。

编辑配置后，请重启 Claude Desktop / Claude Code，以便加载新服务。

使用方法

注册后，只需自然地与 Claude 对话——它会自动选择合适的工具。例如：

• “列出我未读的邮件”
• “搜索自 2026-01-01 以来来自 [email protected] 的邮件”
• “读取 Sarah 发来的那封关于合同的邮件”
• “下载那封账单邮件中的附件”
• “创建一个名为 Receipts 的文件夹”
• “将这封邮件移到 Receipts 文件夹”
• “将这封邮件移到垃圾箱” / “永久删除这封垃圾邮件”
• “将那封邮件标记为已读” / “将它标记为未读”
• “这个邮箱里有哪些文件夹？”

Agent 技能

skills/yahoo-mail/SKILL.md 是一项可选的 Agent 技能，用于教会 Agent 在何时以及如何安全地使用这些工具（默认软删除、确认批量更改、将邮件内容视为不可信信息）。将 skills/yahoo-mail/ 文件夹复制到 ~/.claude/skills/（或项目的 .claude/skills/）中。使用此技能需要先注册上方的 MCP 服务。

工具参考

工具	用途	关键参数
list_folders	列出所有 IMAP 文件夹/标签及其特殊用途标记	（无）
create_folder	创建文件夹（若文件夹已存在则不执行操作；具备幂等性）	name
list_emails	列出文件夹中的近期邮件，按时间从新到旧排序	folder="INBOX"、limit=20、unread_only=False
search_emails	按发件人/主题/日期范围/未读状态搜索文件夹，条件之间采用 AND 组合	folder、sender、subject、since（YYYY-MM-DD）、before、unread_only、limit
read_email	获取完整标头和正文（纯文本，或去除 HTML 后的文本）及附件文件名	uid、folder="INBOX"
get_attachment	获取一个附件的原始字节，并以 base64 编码	uid、filename、folder="INBOX"
move_email	按 UID 在文件夹间移动单封邮件	uid、from_folder、to_folder
delete_email	删除邮件——默认软删除（移至垃圾箱）	uid、folder="INBOX"、permanent=False
mark_email	设置/取消已读（\Seen）标记	uid、folder="INBOX"、read=True

安全行为说明

• delete_email(permanent=False)（默认设置）会将邮件移至垃圾箱，且可以恢复。permanent=True 会立即彻底删除邮件——调用方必须明确选择此操作。
• move_email 和 delete_email 会先获取邮件信封以确认邮件存在，并在结果中返回其主题和发件人，供你核实操作对象是否正确。
• 所有操作都通过 IMAP UID 定位邮件；UID 在会话之间保持有效（绝不使用可能发生变化的序列号）。
• IMAP 错误会以结构化的 {"error": ..., "error_type": ...} 字典返回给调用方，而不是原始异常或堆栈跟踪。

免责声明

这是一个独立的非官方项目，与 Yahoo、Oath/Verizon Media 或 Anthropic 均无关联，也未获得它们的认可或赞助。本项目使用标准 IMAP 协议和账户专用的 App Password 与 Yahoo Mail 通信，不涉及 Yahoo API 密钥或 OAuth。使用此工具须遵守 Yahoo 自身的服务条款。本项目按原样提供，不作任何保证——请参阅 LICENSE。

贡献

欢迎提交问题和拉取请求——请参阅 CONTRIBUTING.md。

许可证

MIT——请参阅 LICENSE。