Hermes Agent MCP on Mac: Dev Toolchain Setup (2026)
Hermes Agent from Nous Research already ships terminal tools, skills, and gateways. Model Context Protocol (MCP) lets Hermes call external tool servers—filesystem roots, GitHub, databases, hosted APIs—without writing a native Hermes tool for each integration. On a Mac, that is how you wire a local dev toolchain into the agent loop while keeping secrets in ~/.hermes/.env.
Upstream: github.com/NousResearch/hermes-agent and the official MCP guide.
Why MCP on Hermes for Mac developers
Developers usually need three surfaces at once: a bounded filesystem for repo work, issue/PR tools (GitHub or Linear), and sometimes an IDE agent that shares messaging or sessions.
Hermes covers the first two as an MCP client (mcp_servers in config). It covers IDE integration as an MCP server via hermes mcp serve so Cursor or Claude Code can read/send Telegram or Discord through your gateway.
Quotable definition: Hermes registers MCP tools as mcp_<server>_<tool_name> (for example mcp_filesystem_read_file), discovers servers at startup, and supports stdio subprocess servers plus HTTP endpoints with optional OAuth 2.1.
If Hermes is not installed yet, complete the Hermes Agent Mac setup guide first—this article assumes hermes doctor passes on macOS 13+ with Node and npx available.
Architecture: config, transports, and tool names
| Piece | Path / command | Role |
|---|---|---|
| MCP config | ~/.hermes/config.yaml → mcp_servers: | Declares stdio or HTTP servers |
| Secrets | ~/.hermes/.env | API keys from catalog install prompts |
| OAuth tokens | ~/.hermes/mcp-tokens/*.json | Remote MCP auth cache (mode 0600) |
| Catalog | hermes mcp | Nous-reviewed one-click MCP installs |
| Reload | /reload-mcp in TUI | Refresh after YAML edits |
| Reverse bridge | hermes mcp serve | Exposes Hermes messaging to MCP clients |
Stdio servers use command, args, and env—ideal for @modelcontextprotocol/server-filesystem on your Mac.
HTTP servers use url and headers (or auth: oauth) for Linear, Stripe, or internal endpoints.
Hermes does not pass your full shell environment to stdio children—only configured env plus a safe baseline. On a headless Mac mini, that complements OpenClaw MCP env under launchd patterns, but Hermes filters at the agent layer.
References: modelcontextprotocol.io and Apple Mac mini specs (16 GB RAM if Docker plus several stdio MCP servers run together).
Seven-step MCP setup runbook on macOS
Step 1 — Confirm MCP extras
Standard install.sh includes MCP. If hermes doctor warns:
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
Verify node --version and npx --version — most catalog servers need Node.
Step 2 — Filesystem server for one repo root
Edit ~/.hermes/config.yaml and add a bounded project path (never your entire $HOME unless intended):
mcp_servers.project_fs with npx -y @modelcontextprotocol/server-filesystem /Users/you/dev/my-app
Step 3 — GitHub MCP from catalog
Run hermes mcp or hermes mcp install github. Hermes prompts for GITHUB_PERSONAL_ACCESS_TOKEN, writes ~/.hermes/.env, and shows a tool checklist — disable destructive tools before confirming.
Step 4 — Optional Codex CLI preset
When codex is on PATH: hermes mcp add codex --preset codex (equivalent to codex mcp-server over stdio).
Step 5 — Whitelist sensitive tools
Under each server set tools.include (e.g. list_issues, create_issue, search_code) and tools.prompts: false so only mcp_github_* tools you need are registered.
Step 6 — Verify in TUI
Run hermes and ask to list files in the project root. After YAML edits use /reload-mcp. For OAuth, use a fresh terminal: hermes mcp login <server> (in-session reload times out at 30s).
Step 7 — Expose Hermes to Cursor
Add "command": "hermes", "args": ["mcp", "serve"] to the client MCP config. Reads work without gateway; sends need hermes gateway — see Hermes Mac setup.
Dev toolchain recipes (stdio vs HTTP)
| Scenario | Transport | Config pattern | When |
|---|---|---|---|
| Monorepo search | stdio | filesystem npx + repo path | Daily MacBook coding |
| PRs / issues | stdio | catalog github + token in .env | Agent triage |
| Codex delegation | stdio preset | hermes mcp add codex --preset codex | Heavy codegen |
| Linear / SaaS | HTTP OAuth | url + auth: oauth | No local daemon |
| Cursor ↔ Telegram | Hermes as server | hermes mcp serve | IDE uses Hermes channels |
Recommendation: Start with one filesystem root plus one catalog server on a laptop. On a 24/7 Mac mini gateway host, limit concurrent stdio MCP processes if RAM is tight.
Use hermes mcp configure github when a server adds new tools. Re-run hermes mcp install <name> after hermes update when catalog manifests change.
Troubleshooting
MCP server not connecting
Pattern: connection errors; no mcp_* tools in the TUI.
Fix: cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]", then hermes doctor. Validate YAML under mcp_servers: and restart Hermes.
Tools not appearing
Pattern: catalog install succeeded but the agent never calls MCP tools.
Causes: enabled: false, narrow tools.include, failed OAuth, or install-time probe failure. Run hermes mcp configure github when the server is online.
OAuth on remote Mac (SSH)
Pattern: browser on laptop, Hermes on a headless Mac.
Fix: paste the redirect URL at the prompt, or use ssh -L to forward the callback port. Prefer hermes mcp login <name> from an interactive SSH session.
FAQ
hermes mcp serve for messaging—or use Hermes alone with mcp_servers for repo tools.mcp_<server>_<tool_name> (dots become underscores). Describe tasks in natural language; the model selects tools.optional-mcps/, but install still runs upstream bootstrap commands. Read the manifest source: URL before production installs.supports_parallel_tool_calls: true per server—only for read-only or non-conflicting tools.hermes mcp install <name> again after hermes update, and hermes mcp configure <name> for new tools.Related reading
Need an always-on Mac?
Optional Mac mini keeps Hermes gateway and MCP stdio servers alive while your laptop sleeps.
