Hermes Agent MCP Mac 配置：扩展本地开发工具链（2026）
Hermes Agent（Nous Research，GitHub，MIT）除 TUI 与网关外，可通过 MCP（Model Context Protocol） 调用外部工具服务器，把本地开发工具链（仓库文件系统、GitHub、Codex CLI 等）接入智能体循环，密钥集中在 ~/.hermes/.env。
为什么在 Mac 上用 MCP 扩展 Hermes
日常开发通常需要：限定目录的文件访问、Issue/PR 类集成，以及偶尔让 IDE 与 Hermes 共用消息通道。
Hermes 作为 MCP 客户端 读取 mcp_servers；作为 MCP 服务端 时执行 hermes mcp serve，供 Cursor / Claude Code 调用 Telegram 等已连接平台。
可引用定义：Hermes 将 MCP 工具注册为 mcp_<server>_<tool>，启动时发现服务器，支持 stdio 子进程与 HTTP（含 OAuth 2.1）。
若尚未安装 Hermes，请先完成 Hermes Agent Mac 安装指南，确保 hermes doctor 通过且已安装 Node/npx。
架构：配置、传输与工具名
| 组件 | 路径/命令 | 作用 |
|---|---|---|
| MCP 配置 | ~/.hermes/config.yaml | 声明 stdio/HTTP 服务器 |
| 密钥 | ~/.hermes/.env | catalog 安装写入的 API Key |
| OAuth | ~/.hermes/mcp-tokens/ | 远程 MCP 令牌缓存 |
| 目录 | hermes mcp | 一键安装审核过的 MCP |
| 重载 | /reload-mcp | TUI 内刷新配置 |
| 反向桥 | hermes mcp serve | 对外暴露 Hermes 消息能力 |
stdio 适合本机 npx 启动的 filesystem/GitHub；HTTP 适合 Linear 等 SaaS。
Hermes 不会把完整 shell 环境传给 stdio 子进程。无头 Mac mini 上还可参考 OpenClaw MCP 与 launchd 环境变量 的分工实践。
外部参考：MCP 规范、Mac mini 规格（多 stdio 服务器建议 16GB 内存）。
macOS 上七步接入 MCP
步骤 1 — 确认 MCP 依赖
标准 install.sh 已包含 MCP。若 hermes doctor 报警：
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
确认 node --version 与 npx --version 可用。
步骤 2 — 绑定单一仓库根目录
编辑 ~/.hermes/config.yaml，在 mcp_servers.project_fs 中配置：
npx -y @modelcontextprotocol/server-filesystem /Users/you/dev/my-app（替换为真实路径，勿挂载整个用户目录）。
步骤 3 — 从 catalog 安装 GitHub
执行 hermes mcp 或 hermes mcp install github，按提示写入 token，并在安装清单中关闭破坏性工具。
步骤 4 — 可选 Codex 预设
hermes mcp add codex --preset codex（需本机 codex 在 PATH 中）。
步骤 5 — 工具白名单
为 GitHub 等服务器设置 tools.include 与 tools.prompts: false，仅注册需要的 mcp_github_* 工具。
步骤 6 — TUI 验证
运行 hermes，要求列出项目根目录文件。修改 YAML 后执行 /reload-mcp。OAuth 请在新终端运行 hermes mcp login <server>。
步骤 7 — 供 Cursor 调用 Hermes
在 Cursor MCP 配置中加入 hermes + mcp serve。读取无需 gateway；发送需 hermes gateway，见 安装指南。
开发场景对照（stdio vs HTTP）
| 场景 | 传输 | 配置要点 | 适用 |
|---|---|---|---|
| 单仓读写 | stdio | filesystem + 仓库路径 | MacBook 日常 |
| Issue/PR | stdio | catalog github + .env | 自动分拣 |
| Codex 委托 | stdio preset | --preset codex | 重度 codegen |
| Linear 等 | HTTP OAuth | auth: oauth | 无本地守护进程 |
| Cursor↔Telegram | Hermes 作 server | mcp serve | IDE 走 Hermes 通道 |
建议：笔记本先「一个 filesystem + 一个 catalog」；确认稳定后再加 HTTP OAuth 与更多 stdio 服务。
故障排除
无法连接 MCP 服务器
现象：连接报错，TUI 中无 mcp_* 工具。
修复：cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"，再运行 hermes doctor，检查 mcp_servers: 缩进后重启。
安装成功但无工具
现象：catalog 安装完成，智能体从不调用 MCP。
原因：enabled: false、tools.include 过窄、OAuth 未完成或安装时探测失败。服务器在线后执行 hermes mcp configure github。
SSH 远程 OAuth
现象：笔记本浏览器，无头 Mac 上跑 Hermes。
修复：在提示处粘贴重定向 URL，或使用 ssh -L 转发回调端口；在交互式 SSH 中运行 hermes mcp login <name>。
FAQ
hermes mcp serve 作为服务端；可与 Cursor 并存。IDE 用 Cursor MCP，消息通道用 Hermes 即可。mcp_<server>_<tool>，点号会变为下划线。用自然语言描述任务即可，模型会自动选择工具。optional-mcps/ 经 PR 审核，但安装仍会执行上游 bootstrap。生产环境请先阅读 manifest 的 source: 仓库地址。supports_parallel_tool_calls: true，仅建议用于只读、无共享写入冲突的工具。hermes update，再对每个条目执行 hermes mcp install <name>；新工具用 hermes mcp configure <name> 勾选。