8d62e4d9d5
- Add src/multitenancy/ with AES-256-GCM credential store, WhatsApp webhook router (phone_number_id -> customerId), and per-customer audit log (90-day Redis TTL) - Add src/billing/ with plan definitions and meterMiddleware that resolves API key -> Customer object with getCredential() closure - Refactor all src/clients/* to accept optional customer param, falling back to env vars for backward compat with single-user mode - Thread customer through handleToolCall(name, args, customer?) - Add customers table to MySQL schema initDatabase() - Add /webhook/whatsapp (immediate 200 + async routing) and /api/connect/* onboarding endpoints to index.ts - Add Redis 7 to docker-compose.yml; add REDIS_URL and CREDENTIAL_ENCRYPTION_KEY to hermes-k8s.yaml - Add product/incubation/ with architecture write-up and PlantUML diagrams (system architecture + 5 user flows) - Extend OpenAPI spec in manifest.ts with all platform endpoints Verification: 3 isolation tests (credential, webhook routing, audit log) passed against live Redis. Deployed to hermes.squaremcp.com. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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