# Yahoo Mail MCP Server — Cleanup Edition

A **remote MCP server** for cleaning up your Yahoo Mail inbox.  
Deploy once to Render.com (free), then connect from **Claude.ai or Claude Desktop on any device** — no local setup needed on any machine.

---

## Tools Available

| Tool | Description |
|---|---|
| `list_inbox` | List recent emails in any folder |
| `search_emails` | Search by sender, subject, age, read status |
| `get_email_body` | Read full body of a specific email |
| `list_folders` | Show all Yahoo Mail folders |
| `get_folder_stats` | Count totals & unread in Inbox/Spam/Bulk |
| `delete_by_sender` | Delete all mail from a sender (dry_run first!) |
| `delete_by_subject` | Delete by subject keyword |
| `delete_older_than` | Delete emails older than N days |
| `delete_by_uids` | Delete specific emails by UID |
| `empty_folder` | Wipe entire Spam or Bulk Mail folder |
| `mark_as_read` | Mark emails as read |
| `unsubscribe_preview` | Find top newsletter senders to bulk-delete |

> **All delete tools default to `dry_run=True`** — they only preview what would be deleted until you explicitly pass `dry_run=False`.

---

## Step 1 — Generate a Yahoo App Password

Yahoo does **not** allow your regular password for IMAP.  
You need a 16-character App Password:

1. Go to → https://myaccount.yahoo.com/security
2. Click **"Generate app password"**
3. Choose **"Other app"** → name it `MCP Server`
4. Copy the 16-character password (shown once — save it!)

---

## Step 2 — Deploy to Render.com (Free)

### Option A — One-click via render.yaml

1. Push this folder to a **private** GitHub repo
2. Go to https://dashboard.render.com → **New → Blueprint**
3. Connect your GitHub repo
4. Render reads `render.yaml` and creates the service automatically
5. In the **Environment** tab, fill in:
   - `YAHOO_EMAIL` → your Yahoo email address
   - `YAHOO_APP_PASSWORD` → the 16-char app password from Step 1
   - `MCP_API_TOKEN` → auto-generated by Render (copy it for Step 3)
6. Click **Deploy**

### Option B — Manual service

1. Go to https://dashboard.render.com → **New → Web Service**
2. Connect your GitHub repo
3. Set **Runtime** = Docker
4. Add Environment Variables:
   ```
   YAHOO_EMAIL          = your.email@yahoo.com
   YAHOO_APP_PASSWORD   = (16-char app password)
   MCP_API_TOKEN        = (generate a random string, e.g. via: python -c "import secrets; print(secrets.token_hex(32))")
   ```
5. Set **Health Check Path** = `/health`
6. Deploy

After deploy you'll get a URL like:  
`https://yahoo-mail-mcp.onrender.com`

---

## Step 3 — Connect Claude Desktop (any machine)

Edit your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "yahoo-mail": {
      "type": "http",
      "url": "https://yahoo-mail-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_TOKEN"
      }
    }
  }
}
```

Replace:
- `yahoo-mail-mcp.onrender.com` → your actual Render URL
- `YOUR_MCP_API_TOKEN` → the token from Render's Environment tab

Restart Claude Desktop — the Yahoo Mail tools will appear under the 🔨 Tools icon.

---

## Connect from Claude.ai (browser / mobile)

1. Go to **claude.ai → Settings → Integrations → Add MCP Server**
2. URL: `https://yahoo-mail-mcp.onrender.com/mcp`
3. Auth: Bearer token → paste `MCP_API_TOKEN`
4. Save — tools appear in every chat automatically

---

## Local Testing (optional)

```bash
cp .env.example .env
# Edit .env with your credentials

pip install -r requirements.txt
uvicorn server:app --reload --port 8000

# Test health
curl http://localhost:8000/health

# Test MCP endpoint (no auth in local dev when MCP_API_TOKEN is blank)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

---

## Example Cleanup Session with Claude

Once connected, you can ask Claude naturally:

> *"Show me my Yahoo Mail inbox stats"*  
> *"Find all newsletters in my inbox"*  
> *"Preview emails from @promotions.example.com"*  
> *"Delete all emails older than 90 days from Bulk Mail — dry run first"*  
> *"Empty my Spam folder"*

---

## Security Notes

- Your Yahoo credentials live **only** in Render's encrypted environment variables — never in code
- All delete operations default to `dry_run=True` — safe by default
- Deletes move to Yahoo Trash (recoverable for 7 days) — not permanent
- Bearer token protects the MCP endpoint from unauthorized access
- Use a **private** GitHub repo so `.env` secrets can't leak

---

## Free Tier Limits (Render)

Render's free web services sleep after 15 minutes of inactivity and take ~30 seconds to wake on first request. For always-on access, upgrade to Render Starter ($7/month) or deploy to Railway / Fly.io.