Hermes Agent CLI MCP 入门指南：连接外部数据和服务
入门20 分钟阅读
Hermes Agent CLI MCP 入门指南：连接外部数据和服务

Hermes Agent CLI MCP 入门指南：连接外部数据和服务

CATAITO Team2026-08-08
你的操作系统:

学习目标

学完本教程后，你将能够：

  • 用通俗的话解释 MCP（Model Context Protocol）是什么
  • 从官方目录中找到 Hermes Agent 可用的 MCP 服务器
  • 用 hermes mcp install / hermes mcp add 为 Hermes Agent CLI 添加 MCP 服务器
  • 理解 ~/.hermes/config.yaml 中的 MCP 配置
  • 在 Hermes Agent 会话中重载并使用 MCP 工具

所需时间： 20 分钟

难度： 入门

本篇覆盖哪个版本？ 本教程覆盖 Hermes Agent CLI——Hermes Agent 的命令行版本。MCP 服务器通过 hermes mcp 命令和 ~/.hermes/config.yaml 文件配置。如果你想要桌面版，请阅读 Hermes Agent 桌面端 MCP 指南。

前置条件

开始之前，请确保已准备以下内容：

要求说明
Hermes Agent 已安装hermes --version 应输出版本号。未安装？请先阅读 Hermes Agent CLI 入门指南。
MCP 支持MCP 随 Hermes Agent 标准安装一同提供，无需额外操作。
一个待连接的 MCP 服务器Hermes Agent 目录自带精选集；本教程以连接 **GitHub MCP 服务器** 为例。

什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，让 Hermes Agent 这样的 AI 助手能够连接到外部工具服务器——GitHub、数据库、文件系统、浏览器栈、内部 API 等等。把它想象成一个通用插头：不必每个工具都各自做定制集成，大家都讲同一种协议。

一个 MCP 服务器 是一个小程序，它向 AI 助手暴露工具、数据或服务。例如：

  • GitHub MCP 服务器 让 Hermes Agent 读取仓库、浏览 issue、审查 pull request
  • filesystem MCP 服务器 让 Hermes Agent 读写工作区之外的文件
  • 搜索 MCP 服务器 让 Hermes Agent 搜索网页并返回实时结果

添加一个 MCP 服务器后，Hermes Agent 会在启动时自动发现它的工具，并在会话中调用——无需手工复制粘贴数据。

Hermes Agent MCP 的工作原理

Hermes Agent 把 MCP 配置保存在 ~/.hermes/config.yaml 中，位于 mcp_servers 下。每个服务器都有两种传输方式之一：

  1. 1本地 stdio —— Hermes Agent 在本地启动的程序，通过标准输入/输出通信。你指定 command 和 args。
  2. 2远程 HTTP —— 托管在其他地方的服务器，通过网络访问。你指定 url，并可选地指定 headers、env 或 auth: oauth。

Hermes Agent 提供三个内置命令来管理 MCP：

  • hermes mcp —— 交互选择器（默认），在这里浏览目录条目并安装、启用、禁用或卸载
  • hermes mcp catalog —— 目录的纯文本列表，便于脚本化使用
  • hermes mcp install <name> —— 按名字一键安装目录条目

此外还有 hermes mcp add <name> 用于添加带 preset 的服务器。

步骤 1：列出官方目录

Hermes Agent 自带一个由 Nous 团队审核并合入的精选 MCP 服务器目录。它们默认全部关闭——只安装你真正需要的。

列出目录中的所有服务器：

Cataito 上的 MCP 目录： 浏览 /zh/mcp — 55+ 经过精选的 MCP 服务器，涵盖 GitHub、数据库、文件系统等

bash
hermes mcp catalog

你应该看到： 可用条目的纯文本列表及其状态。例如：

code
n8n          available              Manage and inspect n8n workflows from Hermes
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

状态值包括 available、installed (disabled) 和 enabled。

步骤 2：安装一个 MCP 服务器

选项 A —— 按名字安装目录服务器（最快）。

从目录安装 GitHub MCP 服务器：

bash
hermes mcp install github

你应该看到： Hermes Agent 引导你填写所需的凭证，然后安装该条目。

选项 B —— 用 preset 添加服务器。

如果服务器支持不同的 preset 变体，你可以显式指定：

bash
hermes mcp add github --preset <preset>

选项 C —— 交互选择器。

hermes mcp 命令打开一个交互选择器。它会展示每个目录条目及其当前状态。按 Enter 选中某一行，即可安装（并逐步填写所需凭证）、启用、禁用或卸载它。

选项 D —— 手动添加服务器（针对目录中没有的服务器）。

直接将服务器写入 ~/.hermes/config.yaml 的 mcp_servers 下。一个本地 stdio 服务器长这样：

yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

需要 API key 的服务器，将令牌存放在 ~/.hermes/.env（Hermes Agent 也会把基础 URL 这类非敏感值写在那里）：

yaml
mcp_servers:
  my-remote:
    url: "https://example.com/mcp"
    headers:
      Authorization: "Bearer your_token"

OAuth 服务器使用 auth 键；首次连接时 MCP 客户端会打开浏览器：

yaml
mcp_servers:
  linear:
    url: "https://api.linear.app/mcp"
    auth: oauth

对于 Google、GitHub 这类第三方提供商，如果你尚未认证，请先运行 hermes auth <provider>。

你应该看到： 保存文件后，该服务器会出现在 hermes mcp catalog 中，状态为 enabled 或 installed (disabled)。

步骤 3：选择要启用的工具

Hermes Agent 安装目录条目时，会先探测 MCP 服务器列出的所有工具，并展示一个勾选清单：

code
Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [ ] create_issue      Create a new issue
  ...

预勾选的行来自：

  1. 1你之前的选择 —— 如果你之前安装过该条目，重新安装会保留你之前的选择（manifest 的默认值不会覆盖它）
  2. 2manifest 的 `tools.default_enabled` —— 如果该条目声明了这一项（有些目录条目会预删破坏性或不常用的工具）
  3. 3全部 —— 如果两者都不适用

按 Enter 提交。只有勾选的工具会写入 mcp_servers.<name>.tools.include。如果你全部勾选，则不写过滤器（最简洁的配置，行为相同）。

如果探测失败（服务器不可达、OAuth 尚未完成，或后端服务未运行），安装仍会成功：manifest 的 tools.default_enabled 会被直接应用，或者不写过滤器。等服务器可连后，运行：

bash
hermes mcp configure <name>

来细化启用的工具。

步骤 4：启动 Hermes Agent 并使用 MCP 工具

在聊天会话中启动 Hermes Agent：

bash
hermes chat

然后让 Hermes Agent 使用已连接的服务，例如：

code
List the files in /home/user/projects and summarize the repo structure

你应该看到： Hermes Agent 发现 MCP 服务器的工具，并像使用任何其他工具一样调用它。

每个 MCP 工具都以 mcp_<server>_<tool> 的名字注册，例如 filesystem 服务器的工具会叫 mcp_filesystem_read_file。

步骤 5：重载或禁用服务器

编辑完 ~/.hermes/config.yaml 后，重载 MCP 让 Hermes Agent 生效：

code
/reload-mcp

你应该看到： Hermes Agent 确认 MCP 配置已重新加载。

要禁用或卸载服务器，使用交互选择器：运行 hermes mcp，按 Enter 选中要改的行，选择禁用或卸载。你也可以直接编辑 ~/.hermes/config.yaml，用 # 注释掉该服务器块，然后用 /reload-mcp 重载。

常见问题

MCP 支持默认包含吗？ 是的——MCP 随 Hermes Agent 标准安装一同提供，无需额外操作。

MCP 配置保存在哪里？ 在 ~/.hermes/config.yaml 的 mcp_servers 下。凭证存放在 ~/.hermes/.env。

MCP 工具怎么命名？ 每个工具以 mcp_<server>_<tool> 注册。

能一键安装目录服务器吗？ 可以——hermes mcp install <name>。

目录服务器会自动工作吗？ 不会。目录条目经过审核、合入 optional-mcps/，但默认全部关闭；你必须手动安装。

能从 Claude Code 迁移 MCP 配置吗？ 可以。~/.claude.json 中的 mcpServers 块映射到 Hermes Agent 的 config.yaml 的 mcp_servers，hermes import-agent claude-code 会自动迁移它（连同 skills 和 instructions）。

编辑配置后怎么重载 MCP？ 在 Hermes Agent 会话中运行 /reload-mcp 命令。

为什么安装前 Hermes Agent 要我读 manifest？ 安装目录条目会运行 manifest 指定的命令（git clone、pip install、npm install 等），最终运行 MCP 服务器自身的代码。manifest 位于 GitHub 上的 optional-mcps/<name>/manifest.yaml，选择器在安装时会打印 source: 链接，让你检查该条目连接或运行的是什么。

下一步

#Hermes Agent#MCP#Model Context Protocol#Integrations
返回教程

相关教程