How to connect Hermes Agent to WhatsApp safely

Hermes Agent can talk to you on WhatsApp, and it can also work with your WhatsApp chats. Those are two different things, and they have very different risk profiles. The built-in connector does the first by giving Hermes the whole WhatsApp account. An MCP server does the second with a short, explicit list of what the agent is allowed to touch.

This guide explains why the default connector is a lot of access to hand to an agent, then connects Hermes to WhatsApp through Automata, a free, open-source WhatsApp MCP server where you decide which chats Hermes can see and which actions it can take.

What you need

• A WhatsApp account. Use a spare number while testing, because unofficial clients carry some risk of rate limits or bans.
• Hermes Agent installed, with a ~/.hermes/config.yaml you can edit.
• Automata, either hosted at mcp.getautomata.app (no server to run), or your own instance with a public HTTPS URL. For self-hosting, the quickest option is the one-click Railway template; you can also self-host with Docker.
• About fifteen minutes.

What the default connector gives Hermes

Hermes ships a WhatsApp gateway built on Baileys, an unofficial library that emulates a WhatsApp Web session. You run hermes whatsapp, scan a QR code under Settings → Linked Devices, and Hermes becomes a linked device on that account. That is a good way to chat with your agent from your phone, and it is why setup takes a minute.

It also means the agent is not a guest in your account. It is the account:

• The session is the account. Hermes stores the session under ~/.hermes/platforms/whatsapp/session, and its own documentation warns that this directory holds full session credentials and “grants full access to the WhatsApp account”. Anything that can read that folder, or any tool the agent can run on that machine, is operating as you.
• Allowlists control who can talk to the agent, not what the agent can reach. Settings such as WHATSAPP_ALLOWED_USERS and the group policy decide whose messages Hermes will answer. They are not a per-chat permission on what Hermes can read or send. The same session can also deliver outbound messages, including scheduled ones through cron, to any chat ID.
• There is no read-only scope. Hermes' documentation describes no way to say “read these two chats and never send”. Reading, replying, and sending all share one set of credentials.
• A loose setting widens it further. WHATSAPP_ALLOWED_USERS=* or WHATSAPP_ALLOW_ALL_USERS=true lets every sender reach an agent that has tools, and a self-chat setup runs it on your personal account.

The usual advice is to dedicate a separate phone number to the bot, and that does limit the blast radius. But a dedicated number only works because the agent then sees nothing you care about. As soon as you want Hermes to summarize your real chats, you are back to giving it the real account.

Why an MCP server is the safe way

MCP (the Model Context Protocol) is the open standard that lets an agent call outside tools. Hermes supports it natively: you add a server to mcp_servers in config.yaml, and Hermes registers that server's tools alongside its own.

With Automata, Automata holds the WhatsApp session, not Hermes. Hermes only gets a connector token, and the token decides what the agent can do:

The permission check happens inside Automata on every request, not in the prompt. A read or send tool refuses a chat that is out of scope, list tools return only allowed chats, and tools you did not enable are never registered for that request. Hermes cannot talk its way into a chat you left off the list. Read more about how Automata enforces permissions.

Step 1: Pair WhatsApp with Automata, not Hermes

Pair your WhatsApp account in the Automata dashboard. This is the same for every client, so follow steps 1 to 3 of How to connect WhatsApp to Claude: deploy or sign up, scan the QR code, and choose the chats you want available.

Step 2: Create a restricted token

In your Automata dashboard, create a connector token just for Hermes. Make three choices:

1. Label it clearly, for example hermes-agent, so you can find and revoke it later.
2. Pick the chats. Allow only the chats Hermes actually needs, such as one team group or a couple of clients. Everything else stays invisible to it.
3. Pick the actions. Start with the read tools. Enable sending only when you want Hermes to reply, and keep it limited to a small allowlist. Action scopes and chat scopes are independent, so a send tool can be on while still restricted to a few chats.

Choose an expiry that fits the job. A 30 or 90 day token is a sensible default for an agent. Automata shows the token once; copy it now. You need two values:

Endpoint: https://your-automata.example.com/mcp
Authorization: Bearer <connector-token>

If you use hosted Automata, the endpoint is always https://mcp.getautomata.app/mcp.

Step 3: Add Automata to Hermes

Store the token in Hermes' environment file so it never lives in your config. Add this line to ~/.hermes/.env:

AUTOMATA_WHATSAPP_TOKEN=<connector-token>

Then add the server to ~/.hermes/config.yaml. Hermes substitutes ${VAR} placeholders in headers from your environment at connect time, so the bearer key is read from .env:

mcp_servers:
  automata_whatsapp:
    url: "https://your-automata.example.com/mcp"
    headers:
      Authorization: "Bearer ${AUTOMATA_WHATSAPP_TOKEN}"

Use the bearer header rather than putting the token in the URL. URLs end up in logs; headers usually do not. The MCP clients docs cover both formats.

Start a new Hermes session, or run /reload-mcp in a running one. Hermes discovers the server, then registers each tool with the prefix mcp_automata_whatsapp_.

Step 4: Test it

Start with a read-only request before asking for anything that sends a message:

Check the WhatsApp connection status.

Then try prompts that match the chats you allowed:

• Summarize what Client A asked for in WhatsApp since Monday.
• List the open action items from the Suppliers group this week.
• Find the delivery date the supplier confirmed.

Now test the boundary, which is the part that proves the setup is safe. Ask Hermes about a chat you did not allow:

What did my family group say yesterday?

It should report that it cannot find or reach that chat. If Hermes can answer, the token is scoped more widely than you intended, or the account is still paired directly in Hermes. Fix that before you rely on it.

Keep it safe

• Start read-only. Give the token read access to one or two chats first, and add write access only where you want Hermes to reply.
• Keep Hermes off the account. Do not run the built-in WhatsApp gateway on the same account that Automata uses.
• One token per agent. Create a separate token for Hermes so you can revoke it without breaking Claude or any other client.
• Rotate on a schedule. Use an expiry, and replace the token when it runs out. If a token appears in a log, a screenshot, or source control, revoke it immediately.
• Remember the limits. Token scopes are strong guardrails on what the agent can reach through Automata, but they do not replace the usual hygiene. Keep a spare number for experiments, and avoid bulk or unsolicited messaging.

Troubleshooting

More fixes are in the troubleshooting guide.

Next steps

• Turn this connection into a daily brief with the free AI chief of staff tutorial.
• Connect more clients, including Claude, ChatGPT, and Cursor, with the MCP clients guide.
• Read the WhatsApp MCP overview for what each tool does and how scoped access compares to other servers.