# Connect Hermes Agent to email: MCP, Himalaya or the email gateway > Connect Hermes Agent to email: a remote MCP server with OAuth in config.yaml, tool filters, approval for write calls, and the Himalaya and gateway routes. Updated: 2026-10-21 · Fact-checked: 2026-10-21 · Canonical: https://commandmail.app/en/guides/connect-hermes-agent-to-email · Deutsch: https://commandmail.app/de/anleitungen/hermes-agent-mit-e-mail-verbinden.md The quickest way to give Hermes Agent email access is a remote MCP server: one entry with `url` and `auth: oauth` in `~/.hermes/config.yaml`, then `hermes mcp login`.[^1] Hermes also ships its own routes: the Himalaya skill for a mailbox over IMAP/SMTP, the Google Workspace skill for Gmail, and an email gateway that lets people write to the agent.[^4][^5][^6] Which one fits depends on whether the agent should run a mailbox of its own, work in the addresses you already use, or simply be reachable by email. Command Mail is our product, so the examples use it as the MCP server. The steps work the same with other email MCP servers that offer Streamable HTTP and OAuth, as long as Hermes can sign in there without an OAuth client of your own, through dynamic client registration or a client metadata document (CIMD). If a provider requires a pre-registered client, the Hermes docs say you add its `oauth.client_id` and `oauth.client_secret` to the entry.[^1][^2] We read the Hermes documentation on 2026-10-21, when the latest release was v0.22.3.[^8] ## Four ways to add email to Hermes The Hermes docs keep apart features that sound alike. The gateway makes Hermes reachable by email; the Himalaya skill lets the agent operate a mailbox.[^4][^5] | Route | Use it for | Sign-in | How the agent works | |---|---|---|---| | Email MCP server | read, sort, draft and send in existing addresses | browser OAuth or a header | tools prefixed `mcp____` | | Himalaya skill | a dedicated agent mailbox over IMAP/SMTP | password or app password in Himalaya | terminal commands, polled by cron | | Google Workspace skill | Gmail, Calendar, Drive | your own Google Cloud project, OAuth | script calls | | Email gateway | people email Hermes, Hermes replies in the thread | mailbox credentials in `~/.hermes/.env` | incoming mail becomes a chat message | Sources: Hermes documentation, retrieved 2026-10-21.[^1][^4][^5][^6] For the gateway and the Himalaya skill, Hermes recommends a dedicated account for the agent and warns against handing it your personal inbox.[^4][^5] An MCP server with fine-grained permissions is the route when Hermes should work in your real addresses without mailbox passwords sitting on the machine. ## What you need You need a current Hermes install; the docs say MCP support is part of the standard install.[^1] You also need an email service with an MCP server and a browser where you can approve the sign-in. Command Mail's server runs at `https://commandmail.app/mcp` with OAuth 2.1, PKCE and dynamic client registration, so you do not create an OAuth client of your own.[^7] On the consent screen you switch each permission on or off: `mail:read` to read, search and organize within the mailbox autonomy level, `mail:draft` for drafts, `mail:send-approved` to send a draft you approved, `mail:send` to send without per-message approval, and `mailboxes` to connect addresses. Sending without approval starts switched off.[^7] The free plan covers one mailbox (further mailboxes pause and keep receiving) and the last 90 days, with reading, search, sorting, the morning brief and drafts, but no sending. Pro adds sending, up to ten mailboxes and full history: €19 per month for the first 100 paying Pro accounts as long as that subscription runs, €29 per month after that, or €190 and €290 a year. You can try Pro for 7 days for €1; Team is €39 per person per month (prices checked 2026-10-21).[^7] ## Step by step: set up an email MCP server in Hermes Setup is one config entry, one sign-in and one reload.[^1] 1. Open `~/.hermes/config.yaml` and add an entry under `mcp_servers`: ```yaml mcp_servers: commandmail: url: "https://commandmail.app/mcp" auth: oauth trust: untrusted ``` You can pick any name; it becomes the tool prefix. The next section explains `trust: untrusted`. 2. Sign in from a fresh terminal: `hermes mcp login commandmail`. Hermes prints an authorize URL, opens your browser when it can, and waits up to five minutes.[^1] If you edit the file from inside a running Hermes session, the CLI reloads MCP connections with a 30-second timeout, which the docs say is too short for an interactive sign-in. Hence the separate terminal. 3. Pick permissions on the consent screen. `mail:read` and `mail:draft` are enough to start. 4. Start a new session with `hermes chat`, or type `/reload-mcp` in the running one.[^1] Hermes caches the tokens in `~/.hermes/mcp-tokens/commandmail.json`, readable only by your user, and refreshes them until a refresh fails.[^1] The tools then appear as, for example, `mcp__commandmail__search_mail` or `mcp__commandmail__get_thread`; in `tools.include` you use the names the server itself reports.[^2] You rarely call them by name; Hermes picks them while it works. If you already set up Command Mail in Claude Code, the docs say `hermes import-agent claude-code` also brings over the MCP servers from `~/.claude.json`.[^1] Run a first task to see whether Hermes is signed in, and use `hermes mcp login` if it is not. ## Approve write calls: trust and tool filters With `trust: untrusted`, Hermes asks before every tool call that is not annotated `readOnlyHint: true`. The default is `full`, where Hermes asks for no approval because a tool can write; only a configured cost limit (`spend_limit`) can still trigger a prompt.[^2] The docs advise `untrusted` for any server you do not fully control. Command Mail annotates its tools to match. Reading, searching and listing carry `readOnlyHint: true`; drafts, sorting actions, rules and sending do not. Under `untrusted`, searches run straight through, and Hermes stops to ask before it archives, drafts or sends. You can also decide which tools Hermes loads at all. With `tools.include`, only the listed tools are registered, and glob patterns such as `*` work.[^1] An entry for an agent that reads and saves drafts but does not sort or send mail: ```yaml mcp_servers: commandmail: url: "https://commandmail.app/mcp" auth: oauth trust: untrusted tools: include: [capabilities, search_mail, list_threads, get_thread, list_attachments, morning_brief, save_agent_draft, list_agent_drafts] ``` With an include list, tools the server adds later stay out until you add them. If you prefer to choose interactively, `hermes mcp configure commandmail` shows a checklist.[^1] Filters in Hermes do not replace permissions at the email service. Command Mail builds its tool list from the permissions you granted: `send_message` and `reply` exist only with `mail:send`, and `send_approved_draft` only with `mail:send-approved`. Sending directly also needs Pro, a mailbox that can send on autonomy `auto`, and room in the daily limit; each email goes to at most 20 recipients.[^7] ## Hermes on a server: signing in without a browser When Hermes runs on a VPS, in a container or over SSH, no browser opens on that machine. In an interactive terminal Hermes offers to paste the redirect URL next to the authorize link.[^1] Open the link on your own computer and approve. The page the browser lands on shows a connection error, which the docs call expected; copy that full URL into the terminal. The remote-hosts guide covers other options, such as forwarding the callback port over SSH.[^3] According to the docs, the Hermes desktop app relays the sign-in to a remote backend automatically when both are up to date.[^1] Hermes only uses device-code login when the authorization server offers it, and Command Mail's OAuth metadata does not list a device endpoint. You can also use a local stdio server instead of the remote one. Command Mail has a CLI for that: `curl -fsSL https://commandmail.app/install.sh | sh`, then `commandmail login`, which also signs in through the browser. `commandmail mcp` then starts a local MCP server that Hermes runs with `command: "commandmail"` and `args: ["mcp"]`.[^7] ## Check that it works Start with `capabilities`. It returns the account owner, the granted permissions, every mailbox with its autonomy level, and the limits. Ask Hermes: "Call capabilities on commandmail and tell me what you are allowed to do." If the answer matches what you chose on the consent screen, the connection is in place. Next, try something read-only: "Find invoices from the last 30 days and list sender, date and amount." Only then let it create a draft; under `trust: untrusted`, Hermes will ask first. Command Mail marks email content as untrusted data and flags suspected prompt injection.[^7] Hermes itself calls email an unauthenticated inbound channel and advises never letting the agent act on unsolicited mail by itself.[^5] Both matter more here because the same Hermes session can often run terminal commands too. ## Scheduled inbox jobs with hermes cron For recurring work such as a morning summary, set up a schedule with `hermes cron add`.[^5] The Hermes Himalaya guide suggests polling an agent mailbox every 15 to 30 minutes and gives a prompt that explicitly forbids acting on instructions in unsolicited mail. For unattended runs, the permissions at the email service are the firmer limit, because no one is there to answer a prompt during a cron run. A morning-summary agent needs `mail:read` and at most `mail:draft`, with no send permission. ## Common problems **Hermes lists tools, but every call times out.** The docs describe this for servers where client registration fails: `tools/list` answers without auth, while real calls time out. `hermes mcp login` now checks that a token actually landed on disk.[^1] Command Mail requires a token even for the tool list; without one the server answers 401 with a pointer to the sign-in. **Sign-in times out.** Five minutes is the default. Set `oauth.timeout` on the server entry to wait longer.[^1] **A write call returns "outcome_uncertain".** Streamable HTTP servers can expire idle sessions. Hermes only replays calls annotated `readOnlyHint: true` on its own; for anything else, check whether the action went through before you run it again.[^2] For an email, look at sent mail or the activity list in Command Mail before you have it sent a second time. **The agent cannot send.** Check the plan first, then the permissions. Sending needs Pro; `mail:send-approved` sends only a draft you approved in Command Mail, and not from a mailbox on `read`.[^7] To change permissions, sign in again with `hermes mcp login commandmail`. ## Next steps How permissions and autonomy levels fit together is covered in [permissions and autonomy](https://commandmail.app/en/docs/permissions-and-autonomy). Whether a self-run IMAP MCP server or a hosted service suits you better is the topic of [IMAP MCP vs hosted MCP](https://commandmail.app/en/learn/imap-mcp-vs-hosted-mcp). For other terminal agents, see [email in Claude Code, Codex and Cursor](https://commandmail.app/en/guides/email-claude-code-codex-cursor). [Start Command Mail for free](https://commandmail.app/login?signup=1) and connect Hermes. ## Frequently asked questions ### How do I add an email MCP server to Hermes Agent? Add it to ~/.hermes/config.yaml under mcp_servers with a url, plus auth: oauth if the server uses OAuth. Then run hermes mcp login in a fresh terminal, approve in the browser, and start a new session or type /reload-mcp. ### Can Hermes Agent send email? Yes, in several ways: through an email MCP tool, through the Himalaya skill over IMAP/SMTP, through the Google Workspace skill for Gmail, or as a reply in the email gateway. Whether it actually sends depends on the permissions at the email service and on Hermes' own approval settings. With Command Mail, any sending needs the Pro plan; sending without per-message approval also needs the mail:send permission and a mailbox on autonomy auto. ### How do I stop Hermes from sending email without asking? Set trust: untrusted on the server entry. Hermes then asks before every tool call that is not annotated readOnlyHint: true. You can also load only read and draft tools with tools.include and not grant a send permission at the email service. ### Does OAuth login work when Hermes runs on a remote server? Yes. In an interactive terminal Hermes offers to paste the redirect URL next to the authorize link. Open the link on your own machine, approve, and paste the full URL the browser ends up on. Command Mail's OAuth metadata does not advertise device-code login. ### Do I need a Google Cloud project to use Gmail with Hermes? Only for the Google Workspace skill, which uses OAuth credentials from your own project. The Hermes docs say the Himalaya skill works with an app password instead. A hosted MCP server like Command Mail needs neither; Gmail arrives there through forwarding. ## Sources 1. [Hermes Agent: MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), accessed 2026-10-21 2. [Hermes Agent: MCP Config Reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference), accessed 2026-10-21 3. [Hermes Agent: OAuth over SSH / Remote Hosts](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh), accessed 2026-10-21 4. [Hermes Agent: Email gateway (IMAP/SMTP)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email), accessed 2026-10-21 5. [Hermes Agent: Give Your Agent Its Own Email Address (Himalaya)](https://hermes-agent.nousresearch.com/docs/guides/agent-email-address), accessed 2026-10-21 6. [Hermes Agent: Google Workspace skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/google-workspace), accessed 2026-10-21 7. [Command Mail: llms.txt with plans, permissions and setup](https://commandmail.app/llms.txt), accessed 2026-10-21 8. [NousResearch: Hermes Agent releases](https://github.com/NousResearch/hermes-agent/releases), accessed 2026-10-21 [^1]: [Hermes Agent: MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp), accessed 2026-10-21 [^2]: [Hermes Agent: MCP Config Reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference), accessed 2026-10-21 [^3]: [Hermes Agent: OAuth over SSH / Remote Hosts](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh), accessed 2026-10-21 [^4]: [Hermes Agent: Email gateway (IMAP/SMTP)](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/email), accessed 2026-10-21 [^5]: [Hermes Agent: Give Your Agent Its Own Email Address (Himalaya)](https://hermes-agent.nousresearch.com/docs/guides/agent-email-address), accessed 2026-10-21 [^6]: [Hermes Agent: Google Workspace skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/google-workspace), accessed 2026-10-21 [^7]: [Command Mail: llms.txt with plans, permissions and setup](https://commandmail.app/llms.txt), accessed 2026-10-21 [^8]: [NousResearch: Hermes Agent releases](https://github.com/NousResearch/hermes-agent/releases), accessed 2026-10-21 --- Command Mail: one inbox for you and your AI agent. Start free: https://commandmail.app/login?signup=1 · Connect your agent: https://commandmail.app/en/agents · MCP: https://commandmail.app/mcp