136bc257d1
- Step-by-step OAuth client registration - OpenAPI schema import instructions - Actions authentication config - Troubleshooting table - Tool availability status
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