yahoo-mail-mcp

A Model Context Protocol (MCP) server for Yahoo Mail over IMAP + SMTP. Gives AI assistants full email management — list, read, search, thread, flag, move, delete/trash, archive, folders, attachments, and send/reply/forward/draft — using your Yahoo app-specific password.

Built with the official MCP SDK, imapflow, mailparser, nodemailer, and zod. TypeScript, MIT licensed.

Features (24 tools)

Read

• list_folders – list all IMAP folders with special-use type

• list_emails – paginated listing with UID, flags, attachment metadata

• read_email – full text/html body, headers, attachment metadata

• search_emails – filter by subject/sender, date range, unread/flagged

• get_thread – reconstruct a conversation via In-Reply-To references

• get_email_stats – per-folder message and unread counts

• extract_contacts – most frequent senders from recent mail

• extract_calendar – parse ICS calendar attachments

Manage

• mark_read / mark_unread

• flag_emails / unflag_emails

• move_emails / delete_emails (to Trash) / archive_emails

• create_folder / rename_folder

Attachments

• list_attachments – metadata only (no body download)

• get_attachment – single attachment as base64 (max 5 MB)

Send (SMTP)

• send_email

• reply_email – sets In-Reply-To / References

• forward_email – quotes the original message

• save_draft / send_draft

Related MCP server: Yahoo Mail MCP Server

Requirements

• Node.js >= 18

• A Yahoo Mail account with 2-step verification enabled and an app-specific password. Generate it at Yahoo Account Security -> Manage app passwords (16 chars, no spaces).

Setup

cp .env.example .env
# edit .env: set YAHOO_EMAIL and YAHOO_APP_PASSWORD
npm install
npm run build

Optional overrides: YAHOO_IMAP_HOST, YAHOO_IMAP_PORT, YAHOO_SMTP_HOST, YAHOO_SMTP_PORT (465 for implicit TLS), YAHOO_MCP_HOST, YAHOO_MCP_PORT, YAHOO_MCP_TOKEN (Bearer token for remote/SSE access).

Usage

stdio (Claude Desktop / Claude Code / Cursor):

{
  "mcpServers": {
    "yahoo-mail": {
      "command": "node",
      "args": ["/absolute/path/to/yahoo-mcp/dist/index.js"],
      "env": {
        "YAHOO_EMAIL": "you@yahoo.com",
        "YAHOO_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

SSE / remote (for Claude.ai or network clients):

YAHOO_MCP_TOKEN=secret npm run start:sse
# SSE endpoint: http://127.0.0.1:3000/sse

If YAHOO_MCP_TOKEN is set, all SSE requests must include Authorization: Bearer <token>.

Verify your credentials first

npm run check:auth

Read-only IMAP login check + SMTP verify() (no mail is ever sent). See scripts/check-auth.ts.

Development

npm run dev          # run src via tsx
npm run build        # tsc -> dist
npm run typecheck    # tsc --noEmit
npm test             # vitest
npm run smoke        # end-to-end: boot server, list tools, list folders

Layout

src/
  index.ts          # MCP server: stdio + optional --sse transport
  config.ts         # zod-validated environment config
  loadEnv.ts        # loads .env then .secrets.env (no dotenv dependency)
  tools.ts          # 24 tool definitions (zod input schemas)
  mail/
    imap.ts         # IMAP service (imapflow, single shared connection)
    smtp.ts         # SMTP service (nodemailer: send/reply/forward/draft)
    types.ts        # shared types
scripts/
  check-auth.ts     # feasibility/auth verification
  smoke.ts          # MCP end-to-end smoke test
  push-all.sh       # push to public + private remotes (see SECURITY.md)
test/               # vitest tests

Design notes (Yahoo realities)

• Yahoo does not advertise IDLE, MOVE, UIDPLUS, or SPECIAL-USE. imapflow transparently emulates MOVE (COPY + delete + EXPUNGE) and special-use is resolved by folder name, so all tools work unchanged.

• No IMAP IDLE watcher, OAuth, or CalDAV/CardDAV: Yahoo doesn't support them, and app passwords avoid OAuth entirely.

• One shared IMAP connection with per-mailbox locks respects Yahoo's limit of ~5 concurrent connections per IP.

Security

• Credentials are read from local .env / .secrets.env files that are never committed. The public repository contains zero secrets.

• Delete is a soft delete (move to Trash); nothing is permanently expunged.

License

MIT. See LICENSE.