Files

garfieldheron 9ecb02785c Remove specific account references from public documentation

- Replace FETCHERPAY with generic CUSTOM account examples
- Update README.md, .env.example, and DEPLOY.md with generic configurations
- Remove hardcoded IPs, email addresses, and domain names
- Update package.json description to be more generic

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-03-05 13:37:51 -05:00

3.6 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 (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)

# 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

# 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

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

3.6 KiB Raw Blame History