Integrations
11. Integrations — Connecting Hermes to the Outside World
Integrations — connecting Hermes to the outside world. If Skills (chapter 10) is “what the agent knows how to do”, then Integrations is “where the agent can reach”. This is the part that decides whether Hermes is truly useful in your day-to-day work or just an isolated chatbot — because no matter how smart an agent is, it is useless if it cannot read a ticket on Jira, cannot see the state of your home’s sensors, or cannot open a PR on GitHub.
The most notable design philosophy
Hermes does not try to cram every integration into the core to “ship one full-feature release”. Instead, it opens up several different extension surfaces, each suited to a different kind of need:
| What you need | Which mechanism to use |
|---|---|
| Connect to a service that already has an MCP server (Postgres, Linear, Figma…) | MCP — no code, configuration only |
| An internal system with no MCP and no Python SDK | A custom plugin — full control, runs locally |
| Just need to call an existing CLI (TTS, STT…) | Config-driven shell command — no Python needed |
| Want to log/block/monitor agent behavior | Hooks (gateway, plugin, or shell) |
| Want Hermes to live in Telegram, Slack, Home Assistant… | Gateway platform |
The cross-cutting principle that the official documentation itself keeps repeating: “connect exactly what you need, with the smallest useful surface” — not “connect everything just in case”. For financial data, customer data, or any operation that could be destructive, the recommendation is always to keep the tool scope as narrow as possible (filter with tools.include, picking only the few tools you need instead of opening up the entire server).
Security is the default, not an add-on
The point repeated across every integration type in the official documentation:
- MCP OAuth: Hermes handles PKCE and token refresh on its own, and does not store raw credentials casually.
- Plugins: opt-in by default — installing one does not mean it runs; you must actively add it to
plugins.enabled. - Home Assistant: by default no events are forwarded until you explicitly declare which domains/entities to watch — so the agent is not “drowned” in noise or accidentally granted overly broad access.
- Obsidian: the Vault mount and
OBSIDIAN_VAULT_PATHare separate configuration concerns, and the path variable does not create a filesystem sandbox. - Certain dangerous domains (shell execution, arbitrary scripts) are hard-locked by default in the Home Assistant integration, regardless of what you configure.
This is not a trivial detail — it is deliberate design: every new integration starts in a disabled/narrow state, and you must actively expand it, rather than the other way around.
An interesting point worth highlighting
GitHub — a name you would expect to appear first in any list of MCP servers — was deliberately excluded from the official MCP catalog, for a legitimate technical reason (GitHub’s hosted MCP requires each client to bring its own OAuth app). Instead, Hermes chose the more pragmatic solution: a set of skills that drive the gh CLI directly. This is a good example of the argument “just because an open standard exists does not mean you should use it — pick whichever approach is genuinely stronger for that use case”.
The structure of the 6 upcoming sub-sections
From here, 11.1–11.7 will go deep into each specific type of connection: the most open and important platform (MCP), one noteworthy special case (GitHub), structured data connections (Databases), a filesystem-based knowledge integration (Obsidian), the SaaS ecosystem via OAuth (SaaS Tools), a complete real-world two-way integration (Home Assistant), and the deepest extension layer for when everything above is not enough (Custom Plugins).