hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-mcp-with-hermes.md

sidebar_position, title, description

sidebar_position	title	description
6	在 Hermes 中使用 MCP	将 MCP 服务器连接到 Hermes Agent、过滤其工具并在实际工作流中安全使用的实践指南

在 Hermes 中使用 MCP

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

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

何时应该使用 MCP？

在以下情况下使用 MCP：

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

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

• 内置 Hermes 工具已能很好地完成该工作
• 服务器暴露了大量危险工具，而你没有准备好对其进行过滤
• 你只需要一个非常窄的集成，原生工具会更简单、更安全

心智模型

将 MCP 视为一个适配器层：

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

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

第一步：安装 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 是一个不错的默认选择。

第二步：先添加一个服务器

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

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

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.

第三步：验证 MCP 已加载

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

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

一个实用的测试 prompt（提示词）：

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

第四步：立即开始过滤

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

示例：仅白名单你需要的内容

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

典型 prompt

加载后，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 可执行文件时，从 /mnt/c/Users/<you> 或 /mnt/c/workspace/... 等 Windows 挂载路径启动 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

2. Hermes 添加的实用工具包装器

• 通过以下方式过滤：
  • tools.resources
  • tools.prompts

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

Resources（资源）：

• list_resources
• read_resource

Prompts（提示词）：

• list_prompts
• get_prompt

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

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

因此，如果服务器不支持 resources/prompts，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"]

好的 prompt：

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

好的 prompt：

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

好的 prompt：

Look up customer ACME Corp and summarize recent invoice activity.

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

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

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

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

好的 prompt：

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
• 从尽可能小的集合开始

禁用未使用的实用工具

如果你不希望模型浏览服务器提供的 resources/prompts，请将其关闭：

tools:
  resources: false
  prompts: false

保持服务器范围狭窄

示例：

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

配置更改后重新加载

/reload-mcp

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

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

按症状排查问题

"服务器已连接，但我期望的工具不见了"

可能原因：

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

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

检查：

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

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

因为 Hermes 现在遵守你的按服务器策略和能力感知注册。这是预期行为，通常也是期望的结果。

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

使用：

enabled: false

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

推荐的首批 MCP 配置

适合大多数用户的首选服务器：

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

不适合作为首选的服务器：

• 具有大量破坏性操作且未经过滤的大型业务系统
• 任何你不够了解、无法加以约束的系统

相关文档

• MCP（模型上下文协议）
• FAQ
• 斜杠命令