跳到主要内容

在 Hermes 中使用 MCP

本指南展示如何在日常工作流中实际使用 Hermes Agent 的 MCP 功能。

如果功能页面解释了 MCP 是什么，那么本指南关注的是如何快速安全地从中获取价值。

什么时候应该使用 MCP？​

在以下情况使用 MCP：

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

不要使用 MCP 的情况：

  • 内置 Hermes 工具已经能很好地解决问题
  • 服务器暴露了大量危险工具，而你没有准备好过滤它们
  • 你只需要一个非常窄的集成，原生工具会更简单安全

心智模型​

将 MCP 视为适配器层：

  • Hermes 仍然是 Agent
  • MCP 服务器提供工具
  • Hermes 在启动或重载时发现这些工具
  • 模型可以像使用普通工具一样使用它们
  • 你控制每个服务器有多少是可见的

最后一点很重要。良好的 MCP 使用不只是"连接一切"，而是"连接正确的东西，使用最小的有用接口"。

步骤 1：安装 MCP 支持​

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

如果你安装时没有额外依赖，需要单独添加 MCP：

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

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

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

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

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

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

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

然后启动 Hermes：

hermes chat

现在问一些具体的问题：

Inspect this project and summarize the repo layout.

步骤 3：验证 MCP 已加载​

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

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

一个实用的测试提示词：

Tell me which MCP-backed tools are available right now.

步骤 4：立即开始过滤​

如果服务器暴露了很多工具，不要等到以后再过滤。

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

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 bridge -> Windows Chrome

为什么这种模式有用​

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

推荐服务器​

使用 chrome-devtools-mcp。

如果你的 Windows Chrome 已经通过 chrome://inspect/#remote-debugging 启用了实时远程调试，在 WSL 中按如下方式添加：

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

保存服务器后：

hermes mcp test chrome-devtools-win

然后启动新的 Hermes 会话或运行：

/reload-mcp

典型提示词​

加载后，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 中的后台/冻结标签并重试。

示例：黑名单危险操作​

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

示例：同时禁用实用包装器​

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

过滤实际上影响什么？​

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

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

你可能看到的实用包装器​

资源：

  • list_resources
  • read_resource

提示词：

  • list_prompts
  • get_prompt

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

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

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

常见模式​

模式 1：本地项目助手​

当你希望 Hermes 在有界工作区中进行推理时，使用 MCP 连接仓库本地文件系统或 git 服务器。

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

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

好的提示词：

Review the project structure and identify where configuration lives.
Check the local git state and summarize what changed recently.

模式 2：GitHub 分类助手​

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

好的提示词：

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

模式 3：内部 API 助手​

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

好的提示词：

Look up customer ACME Corp and summarize recent invoice activity.

在这类场景中，严格的白名单远优于排除列表。

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

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

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

好的提示词：

List available MCP resources from the docs server, then read the onboarding guide and summarize it.
List prompts exposed by the docs server and tell me which ones would help with incident response.

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

以下是一个实用的演进流程。

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

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 并询问：

Search the codebase for references to MCP and summarize the main integration points.

阶段 2：仅在需要时扩展​

如果后来你还需要更新 issue：

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

然后重载：

/reload-mcp

阶段 3：使用不同策略添加第二个服务器​

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 可以组合使用它们：

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

这就是 MCP 变得强大的地方：多系统工作流，无需更改 Hermes 核心。

安全使用建议​

对危险系统优先使用白名单​

对于任何金融、面向客户或具有破坏性的系统：

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

禁用未使用的实用工具​

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

tools:
  resources: false
  prompts: false

保持服务器范围狭窄​

示例：

  • 文件系统服务器根目录限于一个项目目录，而非整个主目录
  • git 服务器指向一个仓库
  • 内部 API 服务器默认以只读工具暴露为主

配置更改后重载​

/reload-mcp

在更改以下内容后执行：

  • include/exclude 列表
  • enabled 标志
  • resources/prompts 开关
  • 认证头 / env

按症状排查故障​

"服务器已连接但我期望的工具缺失"​

可能原因：

  • 被 tools.include 过滤
  • 被 tools.exclude 排除
  • 实用包装器通过 resources: false 或 prompts: false 禁用
  • 服务器实际上不支持 resources/prompts

"服务器已配置但什么都没有加载"​

检查：

  • enabled: false 是否留在配置中
  • 命令/运行时是否存在（npx、uvx 等）
  • HTTP 端点是否可达
  • 认证 env 或 headers 是否正确

"为什么我看到的工具比 MCP 服务器宣告的少？"​

因为 Hermes 现在遵循你的按服务器策略和感知能力的注册机制。这是预期行为，通常是理想的。

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

使用：

enabled: false

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

推荐的首个 MCP 设置​

大多数用户的好的第一个服务器：

  • filesystem
  • git
  • GitHub
  • fetch / 文档 MCP 服务器
  • 一个窄范围的内部 API

不太好的第一个服务器：

  • 有大量破坏性操作且没有过滤的庞大业务系统
  • 任何你不够了解而无法约束的系统

相关文档​