给 Hermes 接上 MCP：从一个本地文件服务开始

Hermes 能聊天，也能调用工具。接入 MCP 后，它还能通过外部服务访问文件、代码仓库或其他系统，而不必把每种能力都写进 Hermes 本身。

这篇用一个最小例子走完整个过程：让 Hermes 通过 MCP 访问指定的项目目录，再检查工具并尝试只读查看项目结构。

连接关系示意图，并非实测截图。文件服务的目录限制不影响 Hermes 其他独立工具。

准备工作

先确认已经安装并配置好 Hermes。官方标准安装包含 MCP 支持；本例使用的文件服务通过 npx 启动，因此还需要 Node.js 和 npm。[1]

hermes --version
node --version
npx --version

准备一个不含敏感数据的项目目录。本文使用 /home/user/my-project 作为示例，操作时请替换成自己的绝对路径，并确认目录存在。本文示例根据官方文档编写，未进行实际运行验证。

1. 配置文件系统 MCP 服务

在终端运行：

hermes config edit

在配置文件顶层添加：

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

如果文件里已经有 mcp_servers:，把 project_fs 加到现有节点下，不要再添加第二个同名顶层节点。这段配置让 Hermes 通过 npx 启动文件系统 MCP 服务，最后一个参数是允许访问的目录。[1]

npx -y 可能在首次运行时从 npm 下载包，先确认你信任包来源。文件系统服务也并不天然只读：即使只打算查看文件，也应检查它实际暴露的工具，避免把整个用户目录作为授权范围。

如果使用多个 Hermes profile，记得在目标 profile 下编辑配置和测试，不要改完一个 profile，却在另一个 profile 中验证。

2. 检查连接和工具

回到终端，查看配置列表：

hermes mcp list

测试服务连接：

hermes mcp test project_fs

按照官方说明，test 会尝试连接服务并列出发现的工具；连接失败时，根据提示检查运行环境、路径和网络。[1]

接着启动 Hermes：

hermes chat

如果原本就有一个 Hermes 会话，修改配置后可以在会话中执行：

/reload-mcp

然后让 Hermes 查看已发现的工具：

请列出 project_fs 提供的 MCP 工具，并说明哪些工具可能修改文件。

确认工具列表后，再给它一个具体、只读的任务：

请使用 project_fs 查看项目目录，列出顶层文件和文件夹，并简要说明项目结构。不要修改任何文件。

看到的目录内容与实际目录相符，才算完成验证；只看到服务名称还不够。

3. 给工具收紧权限

文件系统服务暴露哪些工具，以测试时实际返回的列表为准。如果只需要其中少数工具，可以使用 tools.include 做白名单。[2]

例如，确认服务实际提供以下工具名后，可以这样配置：

mcp_servers:
  project_fs:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/my-project"
    tools:
      include:
        - list_directory
        - read_text_file

保存后，在 Hermes 会话中再次执行 /reload-mcp，然后检查工具列表。

include 过滤的是 MCP 服务原生工具名，不要照抄 Hermes 展示的带服务前缀的工具名。白名单只限制该 MCP 服务暴露给 Hermes 的工具，不等于限制 Hermes 的终端或其他文件工具。[2]

4. 换成远程 MCP 服务

如果服务由其他系统提供，通常会给出一个 HTTP 地址。配置形式与本地命令不同：[2]

mcp_servers:
  docs:
    url: "https://mcp.example.com/mcp"

上面的地址只是格式示例，不能直接拿来连接；需要替换成服务提供方给出的实际 MCP 地址。

某些远程服务使用 OAuth 登录，可以在服务配置中加入 auth: oauth，具体授权方式以服务提供方文档为准。若服务使用令牌，避免把真实令牌写进文章、截图或代码仓库；Hermes 支持在服务配置中通过环境变量引用敏感值。[2]

遇到问题先看哪里？

hermes mcp test project_fs 连接失败：先检查 npx 是否能运行、示例路径是否已替换且存在，以及首次下载所需的网络是否可用。再看测试命令输出的具体错误。

服务连接成功，却找不到某个工具：查看 tools.include 或 tools.exclude，并确认服务本身确实提供该工具。修改配置后执行 /reload-mcp。[1][2]

修改了配置，没有看到变化：确认编辑的是目标 profile 的配置，然后在当前会话执行 /reload-mcp；也可以启动新会话再检查。[1]

想临时停用服务：在该服务的配置下添加 enabled: false，保存并重新加载后，Hermes 不会连接该服务，但配置仍会保留。[2]

从一个目录、几个工具开始就够了。等连接和权限边界都看清楚，再逐步接入代码仓库或远程服务，会比一开始开放一大堆工具更容易排查问题。

参考资料

[1] Hermes 官方指南：Use MCP with Hermes

[2] Hermes 官方文档：MCP Config Reference

[3] Hermes 官方文档：MCP