# 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** (IMAP/SMTP).

---

## Features

- Read, search, and send email from Claude via MCP
- Multi-account support: Yahoo Mail and custom IMAP/SMTP servers
- Streamable HTTP transport (MCP 1.x) + legacy SSE endpoint
- Automatic session recovery after server restarts
- Docker and Kubernetes deployment ready

---

## 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` parameter allows you to specify which configured mailbox to use (defaults to `"yahoo"`).

---

## 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

# Optional: Self-hosted mail server (any IMAP/SMTP server)
# CUSTOM_EMAIL=you@yourdomain.com
# CUSTOM_PASSWORD=yourpassword
# CUSTOM_IMAP_HOST=mail.yourdomain.com
# CUSTOM_IMAP_PORT=993
# CUSTOM_SMTP_HOST=mail.yourdomain.com
# CUSTOM_SMTP_PORT=587

PORT=3456
```

---

## 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 │  │ Custom IMAP/   │
                    │            │  │ SMTP Server    │
                    │            │  │ (optional)     │
                    └────────────┘  └───────────────┘
```

---

## Tech Stack

- **Runtime:** Node.js + TypeScript
- **MCP SDK:** `@modelcontextprotocol/sdk`
- **IMAP:** `imapflow`
- **SMTP:** `nodemailer`
- **HTTP:** `express`
- **Deployment:** Docker + MicroK8s

---

## License

MIT