ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-MCP（模型上下文协议）

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

MCP 让 Hermes Agent 能够连接外部工具服务器，从而使 Agent 可以使用 Hermes 本身之外的工具——GitHub、数据库、文件系统、浏览器栈、内部 API 等。

如果你曾经希望 Hermes 使用某个已存在于别处的工具，MCP 通常是最简洁的实现方式。

MCP 能为你提供什么

  • 无需先编写原生 Hermes 工具，即可访问外部工具生态
  • 在同一配置中支持本地 stdio 服务器和远程 HTTP MCP 服务器
  • 启动时自动发现并注册工具
  • 当服务器支持时，为 MCP 资源和提示提供实用包装器
  • 按服务器过滤，只暴露你真正希望 Hermes 看到的 MCP 工具

快速开始

  1. 安装 MCP 支持（如果你使用了标准安装脚本，则已包含）：
bash
cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
  1. 在 ~/.hermes/config.yaml 中添加一个 MCP 服务器：
yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
  1. 启动 Hermes：
bash
hermes chat
  1. 让 Hermes 使用由 MCP 支持的能力。

例如：

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

Hermes 会自动发现 MCP 服务器的工具，并像使用其他工具一样使用它们。

目录：经 Nous 批准的 MCP 一键安装

Hermes 内置了一份经过筛选的 MCP 服务器目录，由 Nous 工作人员审核并合并。默认处于禁用状态——只安装你实际需要的。

bash
hermes mcp                # 交互式选择器（默认）
hermes mcp catalog        # 纯文本列表，可脚本化
hermes mcp install n8n    # 按名称安装目录条目

选择器会显示每个条目的当前状态：

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

在某一行上按 Enter 即可安装（并完成任何必需的凭证配置）、启用、禁用或卸载。目录条目存储在 hermes-agent 仓库的 optional-mcps/ 目录下——出现在该目录中即代表获得 Nous 批准。没有社区提交层级；条目通过合并 PR 添加。

目录条目可能需要：

  • API 密钥 — Hermes 在安装时提示输入，并将值写入 ~/.hermes/.env。非敏感值（如 base URL）也写入同一文件。
  • OAuth（远程 MCP）— 在配置中写作 auth: oauth；MCP 客户端在首次连接时打开浏览器。
  • OAuth（第三方提供商，如 Google/GitHub）— 如果你尚未认证，Hermes 会引导你执行 hermes auth <provider>。

安装时的工具选择

配置凭证后，Hermes 会探测 MCP 服务器，列出其暴露的所有工具，并展示一个勾选清单：

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

默认勾选的行来自：

  1. 你之前的选择（如果你曾安装过该条目，重新安装会保留你之前的设置——清单默认值不会覆盖）
  2. 清单中的 tools.default_enabled（如果该条目声明了默认值，部分目录条目会预先剔除变更类或很少使用的工具）
  3. 全部工具（如果以上两者均不适用）

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

如果探测失败（服务器不可达、OAuth 尚未完成、后端服务未运行），安装仍会成功：直接应用清单中的 tools.default_enabled（如果已声明），否则不写入任何过滤器。待服务器可达后，重新运行 hermes mcp configure <name> 进行细化。

信任模型

安装目录条目会执行清单指定的任何内容——git clone、条目的 bootstrap 命令（pip install、npm install 等），以及最终的 MCP 服务器自身代码。清单通过 PR 审核进入 hermes-agent 仓库，因此 Nous 在发布前已审核每个条目——但你仍应在安装前阅读清单，特别是 source: 字段对应的仓库、install.bootstrap: 命令以及任何 transport.command: 调用。

清单位于 GitHub 的 optional-mcps/<name>/manifest.yaml。选择器在安装时也会打印清单的 source: URL，以便你快速验证上游仓库。

清单版本兼容性

清单固定了 manifest_version。目录是向前兼容的：如果某个 PR 添加的条目的 manifest_version 高于你已安装的 Hermes 所支持的版本，选择器会显示警告（⚠ '<name>' requires a newer Hermes），而不是静默隐藏该条目。看到该提示时，运行 hermes update 安装最新版 Hermes。

运行时 ${ENV_VAR} 替换

在条目的 transport.command、transport.args、transport.url 和 headers 中，${VAR} 占位符在服务器连接时从环境变量解析（包括 ~/.hermes/.env 中的所有内容）。当目录条目需要引用用户在别处配置的值时，这很有用——例如 ${HOME}/foo 或 ${MY_PROVIDER_TOKEN}。

注意这与目录清单中的 ${INSTALL_DIR} 不同，后者在安装时被替换为目录克隆条目仓库的路径。

稍后更新工具选择

bash
hermes mcp configure linear

重新打开相同的勾选清单，并预勾选你当前的选项。当你希望启用更多工具，或服务器新增了你想要加入的工具时，可使用此命令。

更新目录清单

MCP 不会自动更新。如果清单版本发生变化，在更新 Hermes 后重新运行 hermes mcp install <name> 进行刷新。

若要向目录添加 MCP，请向 optional-mcps/ 提交 PR。

两种 MCP 服务器

Stdio 服务器

Stdio 服务器作为本地子进程运行，通过 stdin/stdout 通信。

yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

在以下情况使用 stdio 服务器：

  • 服务器安装在本地
  • 你希望低延迟访问本地资源
  • 你正在遵循展示 command、args 和 env 的 MCP 服务器文档

HTTP 服务器

HTTP MCP 服务器是 Hermes 直接连接的远程端点。

yaml
mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

在以下情况使用 HTTP 服务器：

  • MCP 服务器托管在别处
  • 你的组织暴露了内部 MCP 端点
  • 你不希望 Hermes 为该集成启动本地子进程

通过 OAuth 认证的 HTTP 服务器

大多数托管 MCP 服务器（Linear、Sentry、Atlassian、Asana、Figma、Stripe 等）需要 OAuth 2.1 而非静态 Bearer Token。设置 auth: oauth，Hermes 会通过 MCP Python SDK 处理发现、动态客户端注册、PKCE、令牌交换、刷新和升级认证。

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

首次连接时，Hermes 会打印授权 URL，并在可能的情况下打开浏览器，然后在本地回环端口等待 OAuth 回调。令牌缓存在 ~/.hermes/mcp-tokens/<server>.json，权限为 0o600；后续运行会静默复用，直到刷新失败。

远程 / 无头主机。 当 Hermes 运行在与浏览器不同的机器上时，回环回调无法到达你的笔记本电脑。有两种方式完成流程：

  • 粘贴回传（无需设置）： 在交互式终端中，Hermes 会在授权 URL 旁打印 "Or paste the redirect URL here…"。在浏览器中打开该 URL，批准授权，复制浏览器最终停留的完整 URL（重定向会显示连接错误——这是正常的），将其粘贴到提示符处。仅包含 ?code=…&state=… 的查询字符串也可以。
  • SSH 端口转发： 在另一个终端中运行 ssh -N -L <port>:127.0.0.1:<port> user@host，然后让重定向流程正常进行。

完整操作指南请参阅 OAuth over SSH / Remote Hosts，包括无需 DCR 的服务器（如 Slack）、预注册的 client_id/client_secret、作用域自定义以及通过 hermes mcp login <server> 重新认证。

陷阱——不支持自动注册的提供商（Google Drive、Atlassian）。 某些服务器会拒绝裸 auth: oauth 所依赖的动态客户端注册步骤（RFC 7591）——Google 的官方 Drive 服务器（https://drivemcp.googleapis.com/mcp/v1）会返回 400 Bad Request，因此不会创建 OAuth 客户端，也不会获取令牌。症状很隐蔽：这些服务器无需认证即可提供 tools/list，因此 hermes mcp login 可以列出工具，看起来像是成功了，但之后每次真正的工具调用都会超时。hermes mcp login 现在会检测这种情况（它会检查令牌是否确实已写入磁盘），并提示你提供自己的 OAuth 客户端。在提供商控制台中创建一个，并添加到配置中：

yaml
mcp_servers:
  googledrive:
    url: "https://drivemcp.googleapis.com/mcp/v1"
    auth: oauth
    oauth:
      client_id: "<your-oauth-client-id>"
      client_secret: "<your-oauth-client-secret>"

然后运行 hermes mcp login googledrive——使用预注册的客户端，Hermes 会跳过注册步骤，执行正常的浏览器授权流程。

陷阱——配置自动重载竞态。 当你在运行中的 Hermes 会话内编辑 ~/.hermes/config.yaml 时，CLI 会以 30 秒超时自动重载 MCP 连接。这对于交互式 OAuth 流程来说不够。先添加条目，然后在一个新终端中运行 hermes mcp login <server>——它会等待完整的 5 分钟，让你完成认证。

mTLS / 客户端证书

支持通过 client_cert / client_key 连接需要双向 TLS（客户端证书认证）的远程 HTTP MCP 服务器。Hermes 将解析后的证书传递给底层 HTTP 客户端以完成 TLS 握手。

client_cert 接受三种形式：

  • 单个合并 PEM 路径——一个文件同时包含证书和私钥：
yaml
mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/.certs/mcp-client.pem"
  • [cert, key] 二元组——证书和私钥分别存放在不同文件中（等
AI 前沿
上一篇

hermes教程-Voice & TTS

下一篇

hermes教程-MCP（模型上下文协议）

分享: