Initial commit: Hermes MCP - Yahoo Mail server for Claude AI

- Multi-account email support (Yahoo + self-hosted IMAP/SMTP) - MCP tools: get_profile, search_messages, read_message, list_folders, create_draft, send_email - Streamable HTTP transport with session recovery - Docker + Kubernetes deployment configuration - Express server with health endpoint 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-03-05 13:14:30 -05:00
commit 356b6b9f55
14 changed files with 1009 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,131 @@
+# Hermes MCP
+
+A multi-account email MCP server for [Claude AI](https://claude.ai).
+Supports **Yahoo Mail** (IMAP App Password) and any **self-hosted mail server** (Dovecot / Poste.io).
+
+---
+
+## Features
+
+- Read, search, and send email from Claude via MCP
+- Multi-account: connect Yahoo and a custom IMAP/SMTP server simultaneously
+- Streamable HTTP transport (MCP 1.x) + legacy SSE endpoint
+- Automatic session recovery after server restarts
+- Deployable to Kubernetes (MicroK8s example included)
+
+---
+
+## Tools
+
+| Tool | Description | Key params |
+|------|-------------|------------|
+| `get_profile` | Get email address for an account | `account` |
+| `search_messages` | Search INBOX by keyword / sender / subject | `q`, `maxResults`, `account` |
+| `read_message` | Read full message body by UID | `uid`, `account` |
+| `list_folders` | List all mailbox folders | `account` |
+| `create_draft` | Save a draft to the Drafts folder | `to`, `subject`, `body`, `account` |
+| `send_email` | Send an email | `to`, `subject`, `body`, `account` |
+
+`account` defaults to `"yahoo"`. Set to `"fetcherpay"` (or whatever you name your second account) for the custom mailbox.
+
+---
+
+## Quick Start (local dev)
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Configure credentials
+cp .env.example .env
+# Edit .env with your email credentials
+
+# 3. Run in dev mode
+npm run dev
+
+# 4. Verify
+curl http://localhost:3456/health
+# → {"status":"ok","service":"hermes-mcp"}
+```
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```env
+# Yahoo Mail — generate an App Password at:
+# https://myaccount.yahoo.com/security → App passwords
+YAHOO_EMAIL=you@yahoo.com
+YAHOO_APP_PASSWORD=xxxx xxxx xxxx xxxx
+
+# Self-hosted mail (Dovecot / Poste.io / any IMAP server)
+FETCHERPAY_EMAIL=you@yourdomain.com
+FETCHERPAY_PASSWORD=yourpassword
+FETCHERPAY_IMAP_HOST=your-mail-server-ip
+FETCHERPAY_IMAP_PORT=993
+FETCHERPAY_SMTP_HOST=your-mail-server-ip
+FETCHERPAY_SMTP_PORT=587
+
+PORT=3456
+```
+
+> **Tip:** Use the server's direct IP for `FETCHERPAY_IMAP_HOST` / `FETCHERPAY_SMTP_HOST` to avoid DNS resolution issues in Kubernetes.
+
+---
+
+## Connecting to Claude.ai
+
+1. Go to **Claude.ai → Settings → Connectors → Add custom connector**
+2. Enter your server URL: `https://your-domain.com/mcp`
+3. Click **Connect**
+
+---
+
+## Production Deployment (Kubernetes)
+
+See [`DEPLOY.md`](./DEPLOY.md) for full instructions covering:
+
+- MicroK8s setup with nginx-ingress and cert-manager
+- Building and pushing a Docker image to the local registry
+- Applying the Kubernetes Deployment / Service / Ingress manifests
+- Zero-downtime redeploys after code changes
+
+---
+
+## Architecture
+
+```
+Claude.ai  ──POST /mcp──►  StreamableHTTPServerTransport
+                                    │
+                          ┌─────────▼──────────┐
+                          │   MCP Server (SDK)  │
+                          │   tools / handlers  │
+                          └──┬──────────────┬───┘
+                             │              │
+                     imapflow (IMAP)   nodemailer (SMTP)
+                             │              │
+                    ┌────────▼───┐  ┌───────▼───────┐
+                    │ Yahoo Mail │  │ Self-hosted    │
+                    │ imap.mail  │  │ Dovecot /      │
+                    │ .yahoo.com │  │ Poste.io       │
+                    └────────────┘  └───────────────┘
+```
+
+---
+
+## Tech Stack
+
+- **Runtime:** Node.js + TypeScript
+- **MCP SDK:** `@modelcontextprotocol/sdk`
+- **IMAP:** `imapflow`
+- **SMTP:** `nodemailer`
+- **HTTP:** `express`
+- **Deployment:** Docker + MicroK8s
+
+---
+
+## License
+
+MIT