Yahoo Mail MCP server

yahoo-mail-mcp

Read, search, organize, and clean up a Yahoo Mail account from Claude — over plain IMAP, no Yahoo API keys required.

An MCP (Model Context Protocol) server that lets an LLM read, search, move, and delete emails in a Yahoo Mail account over IMAP.

Tools exposed: listfolders, createfolder, listemails, searchemails, reademail, getattachment, moveemail, deleteemail, mark_email.

Every tool opens a short-lived IMAP connection, does its work, and closes it. Deletion defaults to moving messages to Trash (found via IMAP special-use flags, not a hardcoded name) — permanent deletion requires the caller to explicitly pass permanent=True. No tool can delete or expunge an entire folder; only single messages by UID.

1. Enable IMAP on your Yahoo account

IMAP access is on by default for most Yahoo Mail accounts. If mail clients can't connect, check: Yahoo Mail → Settings → More Settings → Mailboxes → [your account] → "Allow apps that use less secure sign in" is not the setting you want here — that's for legacy password auth. Modern Yahoo requires an App Password instead (see below), which works whether or not that legacy toggle is on. If you still see connection issues, sign in to Yahoo Account Security and confirm the account isn't locked or flagged for suspicious activity.

2. Generate a Yahoo App Password

Yahoo blocks IMAP logins using your normal account password once two-step verification is enabled (and recommends app passwords generally). To generate one:

app passwords).

1. Go to .
2. Turn on Two-step verification if it isn't already on (required for

"Manage app passwords").

1. Find "Generate app password" (sometimes under "App passwords" /

only shows it once.

1. Choose "Other app", name it something like yahoo-mail-mcp, and generate.
2. Copy the generated password (usually 16 characters, no spaces) — Yahoo

Use this app password as YAHOOAPPPASSWORD, never your real account password.

3. Install dependencies

Requires Python 3.10+.

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

4. Configure credentials

cp .env.example .env

Edit .env and fill in:

YAHOO_EMAIL=you@yahoo.com
YAHOO_APP_PASSWORD=your16charapppassword

.env is already in .gitignore — never commit it.

5. Sanity-check connectivity

Before wiring the server into Claude, confirm your credentials work:

python test_connection.py

This logs in, lists your folders, and prints the 3 most recent inbox emails. It never prints your app password.

6. Run the server

python server.py

The server speaks MCP over stdio — it's meant to be launched by an MCP client (Claude Desktop, Claude Code), not run standalone for interactive use.

7. Register with Claude Desktop / Claude Code

Add an entry to your MCP config pointing at this project's venv Python and server.py. Use absolute paths.

Claude Desktop (~/Library/Application Support/Claude/claudedesktopconfig.json on macOS):

{
  "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": "you@yahoo.com",
        "YAHOO_APP_PASSWORD": "your16charapppassword"
      }
    }
  }
}

Claude Code — add the same server via the CLI:

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

or add it directly to your Claude Code MCP config file with the same JSON shape as above.

Shortened. The full README is on GitHub.