{
  "markdown": "# yahoo-mail-mcp\n\n![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)\n![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)\n![MCP](https://img.shields.io/badge/MCP-compatible-6b46c1.svg)\n\n> Read, search, organize, and clean up a Yahoo Mail account from Claude — over plain IMAP, no Yahoo API keys required.\n\nAn MCP (Model Context Protocol) server that lets an LLM read, search, move,\nand delete emails in a Yahoo Mail account over IMAP.\n\nTools exposed: `list_folders`, `create_folder`, `list_emails`, `search_emails`,\n`read_email`, `get_attachment`, `move_email`, `delete_email`, `mark_email`.\n\nEvery tool opens a short-lived IMAP connection, does its work, and closes it.\nDeletion defaults to moving messages to Trash (found via IMAP special-use\nflags, not a hardcoded name) — permanent deletion requires the caller to\nexplicitly pass `permanent=True`. No tool can delete or expunge an entire\nfolder; only single messages by UID.\n\n## 1. Enable IMAP on your Yahoo account\n\nIMAP access is on by default for most Yahoo Mail accounts. If mail clients\ncan't connect, check: **Yahoo Mail → Settings → More Settings → Mailboxes →\n[your account] → \"Allow apps that use less secure sign in\"** is *not* the\nsetting you want here — that's for legacy password auth. Modern Yahoo\nrequires an **App Password** instead (see below), which works whether or not\nthat legacy toggle is on. If you still see connection issues, sign in to\n[Yahoo Account Security](https://login.yahoo.com/account/security) and\nconfirm the account isn't locked or flagged for suspicious activity.\n\n## 2. Generate a Yahoo App Password\n\nYahoo blocks IMAP logins using your normal account password once two-step\nverification is enabled (and recommends app passwords generally). To\ngenerate one:\n\n1. Go to <https://login.yahoo.com/account/security>.\n2. Turn on **Two-step verification** if it isn't already on (required for\n   app passwords).\n3. Find **\"Generate app password\"** (sometimes under \"App passwords\" /\n   \"Manage app passwords\").\n4. Choose \"Other app\", name it something like `yahoo-mail-mcp`, and generate.\n5. Copy the generated password (usually 16 characters, no spaces) — Yahoo\n   only shows it once.\n\nUse this app password as `YAHOO_APP_PASSWORD`, never your real account\npassword.\n\n## 3. Install dependencies\n\nRequires Python 3.10+.\n\n```bash\ncd yahoo-mail-mcp\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n## 4. Configure credentials\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and fill in:\n\n```\nYAHOO_EMAIL=you@yahoo.com\nYAHOO_APP_PASSWORD=your16charapppassword\n```\n\n`.env` is already in `.gitignore` — never commit it.\n\n## 5. Sanity-check connectivity\n\nBefore wiring the server into Claude, confirm your credentials work:\n\n```bash\npython test_connection.py\n```\n\nThis logs in, lists your folders, and prints the 3 most recent inbox emails.\nIt never prints your app password.\n\n## 6. Run the server\n\n```bash\npython server.py\n```\n\nThe server speaks MCP over stdio — it's meant to be launched by an MCP\nclient (Claude Desktop, Claude Code), not run standalone for interactive use.\n\n## 7. Register with Claude Desktop / Claude Code\n\nAdd an entry to your MCP config pointing at this project's venv Python and\n`server.py`. Use absolute paths.\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`\non macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"yahoo-mail\": {\n      \"command\": \"/absolute/path/to/yahoo-mail-mcp/.venv/bin/python\",\n      \"args\": [\"/absolute/path/to/yahoo-mail-mcp/server.py\"],\n      \"env\": {\n        \"YAHOO_EMAIL\": \"you@yahoo.com\",\n        \"YAHOO_APP_PASSWORD\": \"your16charapppassword\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code** — add the same server via the CLI:\n\n```bash\nclaude mcp add yahoo-mail /absolute/path/to/yahoo-mail-mcp/.venv/bin/python /absolute/path/to/yahoo-mail-mcp/server.py\n```\n\nor add it directly to your Claude Code MCP config file with the same JSON\nshape as above.\n\nIf you'd rather not put the app password in the MCP config's `env` block,\nomit `env` there and rely on `.env` next to `server.py` instead — the server\nloads it automatically via `python-dotenv`.\n\nRestart Claude Desktop / Claude Code after editing the config so it picks up\nthe new server.\n\n## Usage\n\nOnce registered, just talk to Claude naturally — it will pick the right tool\nautomatically. For example:\n\n- \"List my unread emails\"\n- \"Search for emails from newsletter@example.com since 2026-01-01\"\n- \"Read that email from Sarah about the contract\"\n- \"Download the attachment from that invoice email\"\n- \"Create a folder called Receipts\"\n- \"Move this email to the Receipts folder\"\n- \"Move this email to trash\" / \"Permanently delete this spam email\"\n- \"Mark that email as read\" / \"Mark it as unread\"\n- \"What folders do I have in this mailbox?\"\n\n### Tool reference\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `list_folders` | List every IMAP folder/label, with special-use flags | *(none)* |\n| `create_folder` | Create a folder if it doesn't already exist (idempotent) | `name` |\n| `list_emails` | List recent emails in a folder, newest first | `folder=\"INBOX\"`, `limit=20`, `unread_only=False` |\n| `search_emails` | Search a folder by sender/subject/date range/unread, AND-combined | `folder`, `sender`, `subject`, `since` (`YYYY-MM-DD`), `before`, `unread_only`, `limit` |\n| `read_email` | Fetch full headers + body (plain text, or HTML stripped) + attachment filenames | `uid`, `folder=\"INBOX\"` |\n| `get_attachment` | Fetch one attachment's raw bytes, base64-encoded | `uid`, `filename`, `folder=\"INBOX\"` |\n| `move_email` | Move a single message between folders by UID | `uid`, `from_folder`, `to_folder` |\n| `delete_email` | Delete a message — soft-delete (Trash) by default | `uid`, `folder=\"INBOX\"`, `permanent=False` |\n| `mark_email` | Set/unset the read (`\\Seen`) flag | `uid`, `folder=\"INBOX\"`, `read=True` |\n\n## Notes on safety behavior\n\n- `delete_email(permanent=False)` (the default) moves the message to Trash\n  and is recoverable. `permanent=True` immediately expunges it — the caller\n  must opt in explicitly.\n- `move_email` and `delete_email` fetch the message's envelope first to\n  confirm it exists, and return its subject/sender in the result so you can\n  verify the right email was touched.\n- All operations address messages by IMAP UID, which stays valid across\n  sessions (never sequence numbers, which can shift).\n- IMAP errors are returned to the caller as structured\n  `{\"error\": ..., \"error_type\": ...}` dicts rather than raw exceptions/stack\n  traces.\n\n## Disclaimer\n\nThis is an independent, unofficial project. It is not affiliated with,\nendorsed by, or sponsored by Yahoo, Oath/Verizon Media, or Anthropic. It\ncommunicates with Yahoo Mail using the standard IMAP protocol and an\naccount-scoped App Password — no Yahoo API keys or OAuth are involved. Use\nof this tool is subject to Yahoo's own Terms of Service. Provided as-is,\nwith no warranty — see [LICENSE](LICENSE).\n\n## Contributing\n\nIssues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 7118,
  "sha": "d70073a7b27432ef5eda4e13c2d628125c6c7892dca63641e591dd9ec927bc86",
  "repo_slug": "andesstriker/yahoo-mail-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_andesstriker_yahoo_mail_mcp_2de71bb7/readme"
}