356b6b9f55
- 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>
132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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
|