Hermes Agent 接入 MCP：模型上下文协议集成指南

MCP（Model Context Protocol，模型上下文协议）为 AI Agent 提供了标准化的工具调用接口，让 Agent 能够连接外部系统、API 和数据源。本文将介绍如何在 Hermes Agent 中集成 MCP 服务器，配置工具过滤策略，以及在实际工作流中安全高效地使用它们。

何时使用 MCP

适合使用 MCP 的场景：

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

不适合使用 MCP 的场景：

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

心智模型

将 MCP 视为一个适配层：

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

最后一点非常重要。好的 MCP 使用方式不是"连接所有东西"，而是"连接正确的东西，暴露最小的有效面"。

步骤一：安装 MCP 支持

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

如果安装时没有包含 extras，需要单独添加 MCP：

bash

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

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

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

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

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

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

yaml

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

然后启动 Hermes：

bash

hermes chat

尝试一个具体的请求：

Inspect this project and summarize the repo layout.

步骤三：验证 MCP 是否加载

可以通过以下方式验证 MCP：

Hermes 启动横幅/状态应显示 MCP 集成信息
询问 Hermes 当前可用的工具
配置变更后使用 /reload-mcp
如果服务器连接失败，检查日志

一个实用的测试提示：

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

步骤四：立即开始过滤

如果服务器暴露了大量工具，不要等到后面再处理。

示例：白名单模式，仅保留所需工具

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

为什么此模式有用

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

典型提示词

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

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

何时不应使用 `/browser connect`

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

常见原因：

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 暴露的功能分为两类：

1. 服务器原生 MCP 工具

通过以下方式过滤：
- tools.include
- tools.exclude

2. Hermes 添加的工具包装器

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

你可能看到的工具包装器

资源（Resources）：

list_resources
read_resource

提示（Prompts）：

list_prompts
get_prompt

这些包装器仅在以下条件满足时出现：

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

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

常见模式

模式一：本地项目助手

当你想让 Hermes 在有限的工作空间中推理时，使用 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"]

推荐提示词：

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

模式二：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

推荐提示词：

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.

模式三：内部 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

推荐提示词：

Look up customer ACME Corp and summarize recent invoice activity.

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

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

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

yaml

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.

教程：端到端配置与过滤实践

以下是完整的配置推进过程。

阶段一：添加 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 并提问：

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

阶段二：按需扩展

如果后续需要议题更新功能：

yaml

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

然后重新加载：

/reload-mcp

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

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

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

这就是 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
command/runtime 存在（npx、uvx 等）
HTTP 端点可达
认证环境变量或请求头正确

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

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

"如何移除 MCP 服务器而不删除配置？"

使用：

yaml

enabled: false

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

字节笔记本

Hermes Agent 接入 MCP：模型上下文协议集成指南

何时使用 MCP

心智模型

步骤一：安装 MCP 支持

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

步骤三：验证 MCP 是否加载

步骤四：立即开始过滤

示例：白名单模式，仅保留所需工具

WSL2：桥接 WSL 中的 Hermes 到 Windows Chrome

为什么此模式有用

推荐服务器

典型提示词

何时不应使用 `/browser connect`

已知问题

示例：黑名单模式，排除危险操作

示例：同时禁用工具包装器

过滤机制详解

你可能看到的工具包装器

常见模式

模式一：本地项目助手

模式二：GitHub 议题管理助手

模式三：内部 API 助手

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

教程：端到端配置与过滤实践

阶段一：添加 GitHub MCP，使用严格白名单

阶段二：按需扩展

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

安全使用建议

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

禁用未使用的工具

保持服务器范围狭窄

配置变更后重新加载

常见问题排查

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

"服务器已配置但没有加载任何内容"

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

"如何移除 MCP 服务器而不删除配置？"

推荐的首次 MCP 配置

字节笔记本

Hermes Agent 接入 MCP：模型上下文协议集成指南

何时使用 MCP

心智模型

步骤一：安装 MCP 支持

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

步骤三：验证 MCP 是否加载

步骤四：立即开始过滤

示例：白名单模式，仅保留所需工具

WSL2：桥接 WSL 中的 Hermes 到 Windows Chrome

为什么此模式有用

推荐服务器

典型提示词

何时不应使用 /browser connect

已知问题

示例：黑名单模式，排除危险操作

示例：同时禁用工具包装器

过滤机制详解

你可能看到的工具包装器

常见模式

模式一：本地项目助手

模式二：GitHub 议题管理助手

模式三：内部 API 助手

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

教程：端到端配置与过滤实践

阶段一：添加 GitHub MCP，使用严格白名单

阶段二：按需扩展

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

安全使用建议

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

禁用未使用的工具

保持服务器范围狭窄

配置变更后重新加载

常见问题排查

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

"服务器已配置但没有加载任何内容"

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

"如何移除 MCP 服务器而不删除配置？"

推荐的首次 MCP 配置

何时不应使用 `/browser connect`