Hermes

AI-powered email MCP server for Zoho Mail. Gives Claude direct access to your inbox so you can read, search, send, and get intelligent daily digests — all from a conversation.

What it does

Hermes is an MCP (Model Context Protocol) server that connects Claude to your Zoho Mail account. Once configured, you can:

• Read your inbox — "What emails did I get today?"
• Search emails — "Find all emails from recruiter@company.com"
• Send emails — "Reply to that thread and say I'm available Thursday"
• Get a scored daily report — AI reads every email, scores it 1-10 by importance, and emails you a prioritized digest
• Set up a watchlist — Tell the AI to flag specific senders, keywords, or patterns (e.g. "interview", "payment overdue")

Requirements

• Python 3.11+
• A Zoho Mail account with IMAP enabled
• Claude Code (or any MCP-compatible client)

Setup

1. Clone and install

git clone <repo-url> hermes
cd hermes
pip install -e ".[dev]"

2. Configure credentials

Copy the example env file and fill it in:

cp .env.example .env

HERMES_EMAIL=you@yourdomain.com
HERMES_PASSWORD=your-zoho-app-password

Zoho App Password: If you have 2FA enabled (you should), generate an app-specific password at Zoho Accounts > Security > App Passwords. Select "Other Apps" when prompted.

IMAP must be enabled in Zoho Mail: Settings > Mail Accounts > IMAP Access > Enable.

3. Register with Claude Code

Add Hermes to your Claude Code MCP configuration. Run:

claude mcp add hermes -- python -m hermes

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hermes": {
      "command": "python",
      "args": ["-m", "hermes"],
      "cwd": "/path/to/hermes",
      "env": {
        "HERMES_EMAIL": "you@yourdomain.com",
        "HERMES_PASSWORD": "your-app-password"
      }
    }
  }
}

4. Verify it works

Start Claude Code and ask:

List my email folders.

If Hermes is configured correctly, Claude will call the list_folders tool and show your Zoho folders.

Tools

Tool	Description
fetch_emails	Get recent emails from any folder, with optional AI scoring
get_email	Read the full content of a specific email
send_email	Send an email (plain text, with optional reply threading)
search_emails	Search emails by keyword
list_folders	List all IMAP folders
mark_read	Mark emails as read
generate_daily_report	Build a scored digest and email it to yourself
get_watchlist	View current watchlist rules
update_watchlist	Modify watchlist rules

Watchlist

The watchlist (watchlist.yaml) lets you tell the AI what matters to you. Rules are applied before AI scoring — critical rules force score 10, ignore rules force score 1.

rules:
  - label: Job opportunity
    priority: critical
    match:
      any_of:
        - keyword: "interview"
        - keyword: "offer letter"

  - label: Newsletter
    priority: ignore
    match:
      any_of:
        - keyword: "unsubscribe"
        - subject: "newsletter"

Priorities: critical (score 10), high (AI boost), low (AI suppress), ignore (score 1).

You can edit the watchlist directly or ask Claude: "Add a watchlist rule to flag emails from billing@example.com as high priority."

Daily Report

Ask Claude to generate a report:

Generate my daily email report.

Or set up a cron job for automatic daily digests:

# Every day at 7am
0 7 * * * cd /path/to/hermes && python -c "from hermes.server import generate_daily_report; generate_daily_report()"

The report scores every email, groups them into Critical / Important / Normal sections, and sends you a formatted HTML email.

Configuration

All configuration is via environment variables (or .env file):

Variable	Required	Default	Description
HERMES_EMAIL	Yes	—	Your Zoho email address
HERMES_PASSWORD	Yes	—	Zoho app password
HERMES_REPORT_RECIPIENT	No	Same as HERMES_EMAIL	Where to send daily reports
HERMES_IMAP_HOST	No	imap.zoho.com	IMAP host (use imap.zoho.eu for EU)
HERMES_SMTP_HOST	No	smtp.zoho.com	SMTP host
HERMES_CLAUDE_MODEL	No	claude-haiku-4-5-20251001	Model for email scoring
HERMES_DB_PATH	No	hermes.db	SQLite cache location
HERMES_WATCHLIST_PATH	No	watchlist.yaml	Watchlist file location

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with output
pytest -v

Architecture

src/hermes/
  server.py        — MCP server and tool definitions
  imap_client.py   — IMAP connection and email parsing
  smtp_client.py   — SMTP email sending
  scorer.py        — AI scoring engine and report generation
  watchlist.py     — Watchlist rule loading and matching
  cache.py         — SQLite cache for scores and report history
  config.py        — Environment-based configuration
  models.py        — Shared data models (Email, ScoredEmail, WatchRule)

The MCP server is stateless — each tool call opens a fresh IMAP/SMTP connection, does its work, and closes. The only persistent state is the SQLite cache (scores and report history) and the watchlist file.