hermes教程-将 MCP 与 Hermes 结合使用

何时应使用 MCP？

在以下情况下使用 MCP：

某个工具已以 MCP 形式存在，且你不想构建原生 Hermes 工具
你希望 Hermes 通过干净的 RPC 层操作本地或远程系统
你需要对每个服务器进行细粒度的暴露控制
你想将 Hermes 连接到内部 API、数据库或公司系统，而无需修改 Hermes 核心

在以下情况下不要使用 MCP：

内置的 Hermes 工具已经能很好地解决问题
服务器暴露了大量危险工具接口，且你尚未准备好进行过滤
你只需要一个非常狭窄的集成，而原生工具会更简单、更安全

心智模型

将 MCP 视为一个适配层：

Hermes 仍然是智能体
MCP 服务器贡献工具
Hermes 在启动或重载时发现这些工具
模型可以像使用普通工具一样使用它们
你可以控制每个服务器的可见范围

最后一点很重要。良好的 MCP 使用不仅仅是“连接一切”，而是“连接正确的东西，并保持最小的有用接口”。

步骤 1：安装 MCP 支持

如果你使用标准安装脚本安装了 Hermes，MCP 支持已经包含在内（安装程序会运行 uv pip install -e ".[all]"）。

如果你安装时没有包含额外组件，需要单独添加 MCP：

bash

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

对于基于 npm 的服务器，请确保 Node.js 和 npx 可用。

对于许多 Python MCP 服务器，uvx 是一个不错的默认选择。

步骤 2：先添加一个服务器

从一个单一、安全的服务器开始。

示例：仅访问一个项目目录的文件系统。

yaml

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

然后启动 Hermes：

bash

hermes chat

现在提出一些具体问题：

检查这个项目并总结仓库布局。

步骤 3：验证 MCP 已加载

你可以通过几种方式验证 MCP：

配置后，Hermes 的横幅/状态应显示 MCP 集成
询问 Hermes 它有哪些可用工具
配置更改后使用 /reload-mcp
如果服务器连接失败，检查日志

一个实用的测试提示：

告诉我当前有哪些 MCP 支持的工具可用。

步骤 4：立即开始过滤

如果服务器暴露了大量工具，不要等到以后。

示例：仅白名单你想要的工具

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

对于敏感系统，这通常是最好的默认设置。

WSL2：将 WSL 中的 Hermes 桥接到 Windows Chrome

这是以下情况下的实用设置：

Hermes 在 WSL2 内运行
你想要控制的浏览器是 Windows 上正常登录的 Chrome
从 WSL 使用 /browser connect 很麻烦或不可靠

在这种设置中，Hermes 不直接连接到 Chrome。而是：

Hermes 在 WSL 中运行
Hermes 启动一个本地 stdio MCP 服务器
该 MCP 服务器通过 Windows 互操作（cmd.exe 或 powershell.exe）启动
MCP 服务器连接到你的实时 Windows Chrome 会话

心智模型：

Hermes (WSL) -> MCP stdio 桥接 -> Windows Chrome

为什么这种模式有用

你保留真实的 Windows 浏览器配置文件、Cookie 和登录状态
Hermes 保持在其支持的 Unix 环境（WSL2）中
浏览器控制通过 MCP 工具暴露，而不是依赖 Hermes 核心浏览器传输

典型提示

加载后，Hermes 可以直接使用 MCP 前缀的浏览器工具。例如：

调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。

何时 `/browser connect` 不是正确的工具

如果 Hermes 在 WSL 中运行，而 Chrome 在 Windows 上运行，即使 Chrome 已打开且可调试，/browser connect 也可能失败。

常见原因：

WSL 无法访问 Chrome 暴露给 Windows 工具的同一主机本地端点
较新的 Chrome 实时调试流程与传统的 ws://localhost:9222 不同
通过 Windows 端的辅助工具（如 chrome-devtools-mcp）更容易附加到浏览器

在这些情况下，将 /browser connect 保留给同环境设置，并使用 MCP 进行 WSL 到 Windows 的浏览器桥接。

已知陷阱

当通过 MCP 使用 Windows stdio 可执行文件时，从 Windows 挂载路径（如 /mnt/c/Users/<you> 或 /mnt/c/workspace/...）启动 Hermes。
如果你从 /root 或 /home/... 启动 Hermes，Windows 可能会在 MCP 服务器启动前发出 UNC 当前目录警告。
如果 chrome-devtools-mcp --autoConnect 在枚举页面时超时，减少 Chrome 中的后台/冻结标签页并重试。

示例：黑名单危险操作

yaml

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

示例：也禁用实用工具包装器

yaml

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

过滤实际影响什么？

Hermes 中 MCP 暴露的功能分为两类：

服务器原生的 MCP 工具
- 通过以下方式过滤：
  - tools.include
  - tools.exclude
Hermes 添加的实用工具包装器
- 通过以下方式过滤：
  - tools.resources
  - tools.prompts

你可能看到的实用工具包装器

资源：

list_resources
read_resource

提示：

list_prompts
get_prompt

这些包装器仅在以下情况下出现：

你的配置允许它们，并且
MCP 服务器会话实际支持这些能力

因此，如果服务器不支持，Hermes 不会假装它有资源/提示。

常见模式

模式 1：本地项目助手

当你希望 Hermes 在有边界的 workspace 上进行推理时，使用 MCP 进行仓库本地文件系统或 git 服务器。

yaml

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

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

好的提示：

检查项目结构，确定配置所在位置。 检查本地 git 状态，总结最近的变化。

模式 2：GitHub 分类助手

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

好的提示：

列出关于 MCP 的未解决问题，按主题聚类，并为最常见的 bug 起草一个高质量的问题。 在仓库中搜索 _discover_and_register_server 的使用，并解释 MCP 工具是如何注册的。

模式 3：内部 API 助手

yaml

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

好的提示：

查找客户 ACME Corp 并总结最近的发票活动。

这种场景下，严格的白名单远优于排除列表。

模式 4：文档/知识服务器

某些 MCP 服务器暴露的提示或资源更像是共享知识资产，而非直接操作。

yaml

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

好的提示：

列出文档服务器上可用的 MCP 资源，然后阅读入门指南并总结。 列出文档服务器暴露的提示，并告诉我哪些有助于事件响应。

教程：带过滤的端到端设置

以下是一个实用的渐进过程。

阶段 1：添加带有严格白名单的 GitHub MCP

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

启动 Hermes 并询问：

在代码库中搜索对 MCP 的引用，并总结主要的集成点。

阶段 2：仅在需要时扩展

如果你之后还需要更新问题：

yaml

tools:
  include: [list_issues, create_issue, update_issue, search_code]

然后重载：

/reload-mcp

阶段 3：添加具有不同策略的第二个服务器

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

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

现在 Hermes 可以结合它们：

检查本地项目文件，然后创建一个 GitHub 问题，总结你发现的 bug。

这就是 MCP 的强大之处：无需修改 Hermes 核心即可实现多系统工作流。

安全使用建议

对危险系统优先使用允许列表

对于任何涉及财务、面向客户或破坏性的系统：

使用 tools.include
从尽可能小的集合开始

禁用未使用的实用工具

如果你不希望模型浏览服务器提供的资源/提示，请关闭它们：

yaml

tools:
  resources: false
  prompts: false

保持服务器范围狭窄

示例：

文件系统服务器根目录为一个项目目录，而不是整个主目录
git 服务器指向一个仓库
内部 API 服务器默认暴露以读取为主的工具

配置更改后重载

/reload-mcp

在更改以下内容后执行此操作：

include/exclude 列表
启用标志
resources/prompts 开关
认证头 / 环境变量

按症状进行故障排除

“服务器连接了，但我期望的工具缺失”

可能的原因：

被 tools.include 过滤
被 tools.exclude 排除
通过 resources: false 或 prompts: false 禁用了实用工具包装器
服务器实际上不支持资源/提示

“服务器已配置，但没有任何内容加载”

检查：

配置中没有遗留 enabled: false
命令/运行时存在（npx、uvx 等）
HTTP 端点可达
认证环境变量或标头正确

“为什么我看到的工具比 MCP 服务器宣传的少？”

因为 Hermes 现在尊重你的每服务器策略和基于能力的注册。这是预期的，通常也是可取的。

“如何在不删除配置的情况下移除 MCP 服务器？”

使用：

yaml

enabled: false

这会保留配置，但阻止连接和注册。

字节笔记本

hermes教程-将 MCP 与 Hermes 结合使用

何时应使用 MCP？

心智模型

步骤 1：安装 MCP 支持

步骤 2：先添加一个服务器

步骤 3：验证 MCP 已加载

步骤 4：立即开始过滤

示例：仅白名单你想要的工具

WSL2：将 WSL 中的 Hermes 桥接到 Windows Chrome

为什么这种模式有用

推荐的服务器

典型提示

何时 `/browser connect` 不是正确的工具

已知陷阱

示例：黑名单危险操作

示例：也禁用实用工具包装器

过滤实际影响什么？

你可能看到的实用工具包装器

常见模式

模式 1：本地项目助手

模式 2：GitHub 分类助手

模式 3：内部 API 助手

模式 4：文档/知识服务器

教程：带过滤的端到端设置

阶段 1：添加带有严格白名单的 GitHub MCP

阶段 2：仅在需要时扩展

阶段 3：添加具有不同策略的第二个服务器

安全使用建议

对危险系统优先使用允许列表

禁用未使用的实用工具

保持服务器范围狭窄

配置更改后重载

按症状进行故障排除

“服务器连接了，但我期望的工具缺失”

“服务器已配置，但没有任何内容加载”

“为什么我看到的工具比 MCP 服务器宣传的少？”

“如何在不删除配置的情况下移除 MCP 服务器？”

推荐的初始 MCP 设置

相关文档

字节笔记本

hermes教程-将 MCP 与 Hermes 结合使用

何时应使用 MCP？

心智模型

步骤 1：安装 MCP 支持

步骤 2：先添加一个服务器

步骤 3：验证 MCP 已加载

步骤 4：立即开始过滤

示例：仅白名单你想要的工具

WSL2：将 WSL 中的 Hermes 桥接到 Windows Chrome

为什么这种模式有用

推荐的服务器

典型提示

何时 /browser connect 不是正确的工具

已知陷阱

示例：黑名单危险操作

示例：也禁用实用工具包装器

过滤实际影响什么？

你可能看到的实用工具包装器

常见模式

模式 1：本地项目助手

模式 2：GitHub 分类助手

模式 3：内部 API 助手

模式 4：文档/知识服务器

教程：带过滤的端到端设置

阶段 1：添加带有严格白名单的 GitHub MCP

阶段 2：仅在需要时扩展

阶段 3：添加具有不同策略的第二个服务器

安全使用建议

对危险系统优先使用允许列表

禁用未使用的实用工具

保持服务器范围狭窄

配置更改后重载

按症状进行故障排除

“服务器连接了，但我期望的工具缺失”

“服务器已配置，但没有任何内容加载”

“为什么我看到的工具比 MCP 服务器宣传的少？”

“如何在不删除配置的情况下移除 MCP 服务器？”

推荐的初始 MCP 设置

相关文档

何时 `/browser connect` 不是正确的工具