# Give Hermes Agent its own email address

Hermes Agent, the open-source agent from Nous Research, can have its own
email address through MCP. Claim a Botmail mailbox, add
`https://botmail.pro/mcp` under `mcp_servers` in `~/.hermes/config.yaml`,
and Hermes registers Botmail's tools at startup as `mcp_botmail_check_inbox`,
`mcp_botmail_reply` and so on. No Gmail app password, IMAP setup or domain
is needed.

Hermes details below are from its
[MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)
and [MCP config reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference),
checked in October 2026.

## 1. Claim a mailbox

Hermes has a terminal, so it can claim the address itself. Ask it:

```text
Read https://botmail.pro/skill.md and claim a mailbox for yourself. Send the invite to my email, then wait for me to approve it.
```

Or claim it yourself from any shell:

```sh
npx botmail claim hermes-ada --human you@example.com
```

Open the email from Botmail, sign in with GitHub, Google or Apple and
approve. Then get the key: ask Hermes for the API key it saved, or read it
from `~/.config/botmail/config.json` if you used the CLI.

## 2. Store the key

Hermes resolves `${VAR}` references in MCP config from the active profile's
`.env`, so the key stays out of `config.yaml`:

```sh
echo 'BOTMAIL_KEY=bm_…' >> ~/.hermes/.env
```

## 3. Add Botmail to config.yaml

```yaml
mcp_servers:
  botmail:
    url: "https://botmail.pro/mcp"
    headers:
      Authorization: "Bearer ${BOTMAIL_KEY}"
    trust: untrusted
```

Then check the connection and load the tools:

```sh
hermes mcp test botmail
```

Inside a running session, `/reload-mcp` picks up the change. If the
variable isn't set, Hermes refuses to connect and names the missing variable
rather than sending a literal `${BOTMAIL_KEY}`.

### What `trust: untrusted` does here

On an untrusted server, Hermes asks you before any tool that isn't marked
read-only. Botmail marks its reading tools (`check_inbox`,
`read_conversation`, `search_mail`, `wait_for_mail`, `get_attachment` and a
few status tools) as read-only, so those run freely. `send_email`, `reply`,
`forward`, `create_draft` and inbox changes like archiving wait for your
approval. That's a good default for an agent that reads mail from
strangers.

To stop Hermes starting new conversations at all, also exclude the send
tool. It can still reply, and it can draft a first email for you to send
from a review link:

```yaml
    tools:
      exclude: [send_email]
```

## Sign in with OAuth instead of a key

Botmail's MCP server also supports OAuth, and Hermes handles discovery,
client registration and token refresh with `auth: oauth`:

```sh
hermes mcp add botmail --url https://botmail.pro/mcp --auth oauth
hermes mcp login botmail
```

Your browser opens a Botmail page where you choose permissions (read, send,
manage) and which mailboxes Hermes may use. Tokens are cached in
`~/.hermes/mcp-tokens/botmail.json`. On a remote machine, use the
paste-back prompt Hermes prints, or an SSH port forward, to finish sign-in.

For `hermes gateway` (Hermes on Telegram, Discord or Slack), prefer the API
key. Hermes' docs say the gateway never opens a browser, so an expired OAuth
grant parks the server until you run `hermes mcp login` again.

## Things to ask Hermes

```text
Check your Botmail inbox and summarize anything unread.
```

```text
Email three caterers near Austin asking for a quote for 40 people on May 9. Write them as drafts and give me the review links.
```

```text
Every morning at 8, check your inbox and message me here if anything needs my answer.
```

```text
Sign up for the Acme beta with your address and wait for the confirmation email.
```

For the last one, `wait_for_mail` blocks up to 30 seconds per call and
returns a cursor Hermes passes back, so it can keep watching for a slow
email. Hermes can also run `npx botmail wait --from acme.com --extract code`
in its terminal; see [Wait for a verification code](https://botmail.pro/guides/wait-for-verification-code).

## Botmail vs connecting your Gmail

Hermes can also reach Gmail, through its hosted connectors or Google's own
MCP server. Those act as you, in your inbox. A Botmail address is separate:
mail to and from Hermes stays in its own mailbox, and a bad prompt can't
reach your personal mail. See
[Is it safe to give AI access to your email?](https://botmail.pro/questions/is-it-safe-to-give-ai-access-to-your-email)

## Limits

On the free plan Hermes gets one mailbox and can email 25 new recipients a
day at first, rising as the account earns trust. Mail to new recipients is
checked for spam and phishing before it goes out. The same mailbox works in
Claude Code, Cursor and other clients; see
[Email MCP server](https://botmail.pro/guides/email-mcp-server).

## Questions

### How do I add a remote MCP server to Hermes Agent?

Add an entry under mcp_servers in ~/.hermes/config.yaml with a url and, for an API key, a headers block such as Authorization: Bearer ${BOTMAIL_KEY}. Hermes reads the variable from ~/.hermes/.env. Run hermes mcp test <name> to check it.

### What are Botmail's tools called in Hermes?

Hermes prefixes MCP tools with mcp_ and the server name, so check_inbox becomes mcp_botmail_check_inbox and reply becomes mcp_botmail_reply.

### Can Hermes Agent use email without a Gmail app password?

Yes. With a Botmail address Hermes reads and sends mail through Botmail's MCP server using an API key or OAuth, with no IMAP, SMTP or app password.

---

Source: https://botmail.pro/guides/hermes-agent-email
Agent instructions: https://botmail.pro/skill.md
All guides: https://botmail.pro/llms.txt