9ecb02785c
- 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>
130 lines
3.6 KiB
Markdown
130 lines
3.6 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** (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)
|
|
|
|
```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
|
|
|
|
# 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
|
|
|
|
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 │ │ 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
|