Yahoo Mail Mcp

yahoo-mail-mcp

[](LICENSE) [](package.json) [](https://modelcontextprotocol.io)

MCP server for Yahoo Mail over IMAP. Read, search, triage, folders/labels, trash, permanent deletion (with a safety guard), and draft creation. Never sends email.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Why IMAP?

Yahoo has no public REST API for mail, and mail OAuth is closed to individual developers. The official path is IMAP (imap.mail.yahoo.com:993) with an app password.

Setup

1. Get a Yahoo app password

• Enable two-step verification on your Yahoo account (required)
• Go to Account → Security → "Generate app password" and copy the 16 characters

2. Store the password securely

On macOS, store it in the Keychain (never in plain-text config):

security add-generic-password -s yahoo-mail-mcp -a "" -w ""

On other platforms, set the YAHOO_APP_PASSWORD environment variable instead (the Keychain lookup is tried first, then this fallback).

3. Install

git clone https://github.com/hugo-cornu/yahoo-mail-mcp.git
cd yahoo-mail-mcp
npm install

4. Register with your MCP client

Claude Code (user scope → available everywhere):

claude mcp add --scope user yahoo-mail --env YAHOO_USER= \
  -- node /path/to/yahoo-mail-mcp/src/server.js

claude mcp list   # yahoo-mail should show as "connected"

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "yahoo-mail": {
      "command": "node",
      "args": ["/path/to/yahoo-mail-mcp/src/server.js"],
      "env": { "YAHOO_USER": "" }
    }
  }
}

Tools (11)

| Tool | Type | Description | |---|---|---| | list_folders | read | Folders + roles (Yahoo spam = "Bulk Mail") | | mailbox_stats | read | Message/unread counts per folder | | search_emails | read | Search by folder/from/subject/unseen/dates, paginated, newest first | | read_email | read | Headers + text body, attachments listed (not downloaded) | | mark_read / mark_unread | write | Batch \Seen flag | | move_emails | write | Batch move (archive, spam, custom folder) | | create_folder | write | Create a folder | | trash_emails | write | Move to Trash (recoverable ~30 days) | | delete_emails | destructive | Permanent deletion — requires confirm: true | | create_draft | write | Draft in Drafts folder (sending is impossible by design) |

Design notes

• Single persistent IMAP connection, serialized operations (mutex) — Yahoo caps

at ~3 connections and rate-limits bulk FETCH (fetches are chunked at 50 with exponential-backoff retry).

• UIDs are per-folder: UIDs from search_emails are only valid for that folder

and while uidValidity is unchanged. Every batch operation takes {folder, uids[]}.

• Folders are resolved explicitly via LIST (Yahoo's SPECIAL-USE is unreliable); the

role names inbox/sent/drafts/trash/spam/archive are accepted everywhere.

• Secrets live in the macOS Keychain only (security find-generic-password at

startup). Dev fallback: YAHOO_APP_PASSWORD env var.

• The IMAP core is generic (connection.js is parameterized by an account

object) → multi-account support is possible later.

Troubleshooting

• Auth failed: regenerate the app password; your regular Yahoo password does

not work over IMAP.

• Rate-limited: lower limit, retry after a moment.
• Logs: written to stderr (view with claude mcp logs yahoo-mail, or run

YAHOO_USER= node src/server.js manually).

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hugo-cornu
• Source: hugo-cornu/yahoo-mail-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.