hermes-mail-gateway
Provides email sending, drafting, searching, and folder management for Gmail accounts via IMAP/SMTP, with reliable sent-verification and durable outbox handling.
Provides email sending, drafting, searching, and folder management for Zoho Mail accounts via IMAP/SMTP, with reliable sent-verification and durable outbox handling.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Hermes Mail Gateway
A minimal, fail-safe multi-account mail gateway and MCP server for Hermes Agent.
Scope
Version 1 targets exactly:
Gmail accounts
Zoho Mail accounts
Generic IMAP/SMTP accounts
Four small MCP tools with
accountIdDurable SQLite outbox and idempotent execution
MIME messages and attachments
Message-ID based Sent verification
Redacted audit logging
It intentionally does not target Outlook, Microsoft Graph, EWS, Apple Mail, Mailtrap, Sieve, JMAP, or provider-specific automation in v1.
Related MCP server: email-mcp-server
Reliability contract
The gateway must never blindly retry an SMTP operation whose delivery outcome is unknown. Every outgoing message receives a durable record and a Message-ID before SMTP is attempted. After an ambiguous outcome, the gateway verifies Sent before any user-approved resend.
Sent-copy policy is explicit per account. provider_managed checks the provider's Sent folder and never adds a second copy (appropriate for providers that save one themselves). gateway_append is available only for generic IMAP/SMTP accounts whose SMTP submission does not save Sent: after SMTP acknowledges a message, the gateway first checks for an exact Message-ID in the configured Sent folder, then appends the persisted raw MIME once with \\Seen only if absent, and verifies the exact Message-ID. An ambiguous APPEND is reconciled by another exact lookup; if still unconfirmed, the outcome is non-retryable SENT_UNVERIFIED. An ambiguous SMTP outcome never triggers APPEND or a resend. Confirm the folder and provider behavior before selecting either policy.
TLS is mandatory for both transports: imaps:// uses implicit TLS, imap:// requires STARTTLS before authentication (no plaintext fallback), smtps:// uses implicit TLS, and smtp:// requires STARTTLS. A failed/undefined IMAP SEARCH, missing candidate, or a lookup exceeding the configured verification bound is not proof of absence: Sent APPEND is refused rather than risking a duplicate.
The pre-APPEND exact lookup and APPEND cannot be atomic against an external IMAP client adding a message with the same Message-ID at the same moment. Use one active send path for an account and keep Message-IDs unique; this policy prevents blind gateway retries but does not promise global exactly-once behavior across other writers.
Project status
The local runtime, all four MCP tools, multi-account configuration composition, bounded IMAP reads/searches, UIDVALIDITY-safe mailbox mutations, durable MIME preparation, To/CC/BCC routing, replies, forwarding, no-retry execution, exact Sent verification, provider-visible draft APPEND, draft preparation/cancellation, and redacted responses are implemented. Hermes/systemd activation remains separate.
Run locally
The process requires an explicit operator configuration file; it does not load .env files or use defaults. Set HERMES_MAIL_CONFIG=/absolute/path/to/config.json and run npm run build && npm start. The file contains non-secret account metadata and keychain:<service>/<account> references only. It must define databasePath, server attachmentRoots, unique accounts, and limits; each account defines its own IMAP/SMTP endpoints, folders, sender, and attachment roots. credentialRef is the IMAP reference. Optional smtpCredentialRef selects a separate SMTP reference; when omitted, SMTP uses credentialRef for backward compatibility. Neither reference is returned by account-listing tools. The process writes MCP protocol messages only to stdout and startup diagnostics only to stderr.
For local verification, use the synthetic fixtures in test/ and the process startup smoke test. The controlled real-provider validation used a separately created disposable database/attachment root, credentials in the host keychain, and configuration outside this repository. It exercised multiple configured accounts through the compiled MCP process; recipient inbox read-back is not included because only sender accounts are configured locally. Never test with a customer or unapproved third-party recipient, and never enable automatic retry.
Folder discovery and mailbox operations are implemented as bounded, account-scoped queries: mail_query with operation:"folders" returns only provider folder path, name, delimiter, and optional specialUse. mail_execute supports one reference-based mutation per call, plus strict {type:"saveDraft", messageId} for a durable PREPARED message with intent:"draft". Destination folders must be discovered selectable folders; no expunge or permanent delete is exposed. List/search/read already support any discovered folder, so drafts use the same existing operations. Draft save uses configured draftsFolder when present, otherwise selectable \\Drafts discovery; it never assumes a localized name or uses Sent. APPEND sets \\Draft, verifies the exact Message-ID, and requires a provider UID or one unambiguous exact-Message-ID verification result. Confirmed saves are durable and idempotent; an interrupted or ambiguous append becomes verification-required and is never blindly retried. References and list/search cursors include IMAP UIDVALIDITY; stale generations return REFERENCE_STALE before any old UID is used. cancelPrepared remains durable and cannot cancel a provider-saved or verification-required draft. Startup changes expired execution leases to audited, verification-required OUTCOME_UNKNOWN without SMTP submission. Query/read limits are configured as maxQueryResults (default 50, maximum 100) and maxReadBytes (default 4,000,000, maximum 25,000,000), alongside existing recipient and attachment limits. The gateway never silently approximates unsupported operations.
Search also accepts a strict provider-neutral search object (from, to, cc, subject, since, before, hasAttachment, isRead, isFlagged, and messageId) in addition to the query string. Representable criteria are compiled to bounded server-side IMAP search; unsupported criteria fail safely without scanning an unbounded mailbox. Attachment metadata remains the default; adding attachmentIndex enables a selected account-bound download with filename, content type, size, SHA-256, and base64 bytes. maxAttachmentDownloadBytes controls the decoded download bound (default 10,000,000 bytes, maximum 25,000,000); base64 adds transport overhead. The current public download path does not enforce the 5,000,000-byte maximum stated in some other documentation. Full-message reads fetch bounded ranges and verify UID, mailbox generation and EOF before parsing; maxReadBytes bounds raw message bytes, including attachments, not heap or process memory. Buffering, concatenation, MIME parsing and attachment copies can use substantially more memory, and concurrent reads multiply memory demand. Expanded threads have an aggregate verified raw-byte budget of min(maxReadBytes * 10, 10,000,000); an individually readable message can exceed it. The budget is checked after each complete per-message read, so one additional read can overshoot it before THREAD_TOO_LARGE is returned; it is not a peak-memory ceiling. There is no selective-body fallback. Oversized, stale, cross-account, and invalid selections are rejected. See capabilities and limits for the precise release boundaries.
Security
No credentials, OAuth tokens, customer mail, real addresses beyond public service identifiers, or local account files belong in this repository. Runtime secrets are stored outside the repository using the host credential store.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email: search, read, fetch attachments; attach files when the MCP client supports inputs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading and sending emails via IMAP and SMTP through the MCP protocol. Supports multiple email accounts and configuration via UI or environment variables.BSD 3-Clause
- AlicenseNot gradedqualityDmaintenanceCross-platform MCP server and CLI for email operations, including send, read, search, and contact management, compatible with Gmail, Outlook, Yahoo, and any IMAP/SMTP providers.29 npm1MIT
- AlicenseBqualityBmaintenanceA unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers, enabling search, send, organize, and batch operations.36208 npm26MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the MCP protocol, supporting sending, reading, searching, replying, forwarding, managing drafts and labels, and saving attachments.6 npm3MIT