Files

garfieldheron 356b6b9f55 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

3.8 KiB

Raw Blame History

Hermes MCP

A multi-account email MCP server for 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)

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

# 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

Go to Claude.ai → Settings → Connectors → Add custom connector
Enter your server URL: https://your-domain.com/mcp
Click Connect

Production Deployment (Kubernetes)

See 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

3.8 KiB Raw Blame History