知识引擎/Hermes 知识引擎/MCP 集成 (MCP Integration)

返回分馆所属主题：核心功能更新于 2026年4月16日官方来源

MCP 让 Hermes Agent 连接到外部工具服务器，使 Agent 能够使用 Hermes 本身之外的工具——GitHub、数据库、文件系统、浏览器栈、内部 API 等。如果你曾想让 Hermes 使用一个已经存在于其他地方的工具，MCP 通常是最简洁的方式。 - 无需先编写原生 Hermes 工具即可访问外

MCP 集成 (MCP Integration)

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

MCP 让 Hermes Agent 连接到外部工具服务器，使 Agent 能够使用 Hermes 本身之外的工具——GitHub、数据库、文件系统、浏览器栈、内部 API 等。

如果你曾想让 Hermes 使用一个已经存在于其他地方的工具，MCP 通常是最简洁的方式。

MCP 提供的功能

无需先编写原生 Hermes 工具即可访问外部工具生态系统
在同一配置中支持本地 stdio 服务器和远程 HTTP MCP 服务器
启动时自动工具发现和注册
当服务器支持时，为 MCP 资源和提示提供实用包装器
每服务器过滤，让你只暴露实际想让 Hermes 看到的 MCP 工具

快速开始

安装 MCP 支持（如果你使用了标准安装脚本，则已包含）：

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

在 ~/.hermes/config.yaml 中添加 MCP 服务器：

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

启动 Hermes：

hermes chat

让 Hermes 使用 MCP 支持的能力。

例如：

List the files in /home/user/projects and summarize the repo structure.

Hermes 会发现 MCP 服务器的工具并像使用其他工具一样使用它们。

两种 MCP 服务器

Stdio 服务器

Stdio 服务器作为本地子进程运行，通过 stdin/stdout 通信。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

在以下情况下使用 stdio 服务器：

服务器在本地安装
你希望低延迟访问本地资源
你正在遵循显示 command、args 和 env 的 MCP 服务器文档

HTTP 服务器

HTTP MCP 服务器是 Hermes 直接连接的远程端点。

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

在以下情况下使用 HTTP 服务器：

MCP 服务器托管在其他地方
你的组织暴露了内部 MCP 端点
你不希望 Hermes 为该集成启动本地子进程

基本配置参考

Hermes 从 ~/.hermes/config.yaml 的 mcp_servers 下读取 MCP 配置。

常用键

键	类型	含义
command	字符串	stdio MCP 服务器的可执行文件
args	列表	stdio 服务器的参数
env	映射	传递给 stdio 服务器的环境变量
url	字符串	HTTP MCP 端点
headers	映射	远程服务器的 HTTP 头
timeout	数字	工具调用超时
connect_timeout	数字	初始连接超时
enabled	布尔值	如果为 false，Hermes 完全跳过该服务器
tools	映射	每服务器的工具过滤和实用工具策略

最小 stdio 示例

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

最小 HTTP 示例

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Hermes 如何注册 MCP 工具

Hermes 为 MCP 工具添加前缀，以避免与内置名称冲突：

mcp_<server_name>_<tool_name>

示例：

服务器	MCP 工具	注册名称
filesystem	read_file	mcp_filesystem_read_file
github	create-issue	mcp_github_create_issue
my-api	query.data	mcp_my_api_query_data

实际上，你通常不需要手动调用带前缀的名称——Hermes 会看到工具并在正常推理时选择它。

MCP 实用工具

当支持时，Hermes 还会为 MCP 资源和提示注册实用工具：

list_resources
read_resource
list_prompts
get_prompt

这些按服务器注册，使用相同的前缀模式，例如：

mcp_github_list_resources
mcp_github_get_prompt

重要说明

这些实用工具现在是能力感知的：

Hermes 只在 MCP 会话实际支持资源操作时才注册资源实用工具
Hermes 只在 MCP 会话实际支持提示操作时才注册提示实用工具

因此，一个暴露可调用工具但不暴露资源/提示的服务器不会获得这些额外的包装器。

每服务器过滤

你可以控制每个 MCP 服务器向 Hermes 贡献哪些工具，从而精细管理你的工具命名空间。

完全禁用服务器

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

如果 enabled: false，Hermes 完全跳过该服务器，甚至不会尝试连接。

白名单服务器工具

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

只有那些 MCP 服务器工具会被注册。

黑名单服务器工具

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

除排除的工具外，所有服务器工具都会注册。

优先级规则

如果两者同时存在：

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include 优先。

同时过滤实用工具

你也可以单独禁用 Hermes 添加的实用工具包装器：

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

这意味着：

tools.resources: false 禁用 list_resources 和 read_resource
tools.prompts: false 禁用 list_prompts 和 get_prompt

完整示例

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

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

如果所有工具都被过滤掉会怎样？

如果你的配置过滤掉了所有可调用工具，并禁用或省略了所有支持的实用工具，Hermes 不会为该服务器创建空运行时 MCP 工具集。

这保持了工具列表的整洁。

运行时行为

发现时间

Hermes 在启动时发现 MCP 服务器，并将其工具注册到正常的工具注册表中。

动态工具发现

MCP 服务器可以在运行时通过发送 notifications/tools/list_changed 通知来告知 Hermes 其可用工具发生了变化。当 Hermes 收到此通知时，它会自动重新获取服务器的工具列表并更新注册表——无需手动 /reload-mcp。

这对于能力动态变化的 MCP 服务器很有用（例如，当加载新的数据库模式时添加工具，或当服务下线时移除工具）。

刷新是锁保护的，因此来自同一服务器的快速连续通知不会导致重叠刷新。提示和资源变更通知（prompts/list_changed、resources/list_changed）会被接收但尚未被处理。

重新加载

如果你更改了 MCP 配置，使用：

/reload-mcp

这会从配置重新加载 MCP 服务器并刷新可用工具列表。对于服务器本身推送的运行时工具变更，参见上面的动态工具发现。

工具集

每个配置的 MCP 服务器在贡献至少一个注册工具时，也会创建一个运行时工具集：

mcp-<server>

这使得 MCP 服务器在工具集级别上更容易理解。

安全模型

Stdio 环境过滤

对于 stdio 服务器，Hermes 不会盲目传递你的完整 Shell 环境。

只有显式配置的 env 和安全基线会被传递。这减少了意外的秘密泄露。

配置级别的暴露控制

新的过滤支持也是一种安全控制：

禁用你不希望模型看到的危险工具
只为敏感服务器暴露最小白名单
当你不希望暴露该层面时禁用资源/提示包装器

示例用例

带最小 Issue 管理的 GitHub 服务器

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

使用示例：

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

移除危险操作的 Stripe 服务器

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

使用示例：

Look up the last 10 failed payments and summarize common failure reasons.

单项目根目录的文件系统服务器

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

使用示例：

Inspect the project root and explain the directory layout.

故障排除

MCP 服务器未连接

检查：

# 验证 MCP 依赖已安装（标准安装中已包含）
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

然后验证你的配置并重启 Hermes。

工具未出现

可能的原因：

服务器连接失败
发现失败
你的过滤配置排除了这些工具
该服务器上不存在该实用工具能力
服务器被 enabled: false 禁用

如果你是有意过滤的，这是预期行为。

为什么资源或提示实用工具没有出现？

因为 Hermes 现在只在两个条件都满足时才注册这些包装器：

你的配置允许它们
服务器会话实际支持该能力

这是有意的，保持了工具列表的准确性。

MCP 采样支持

MCP 服务器可以通过 sampling/createMessage 协议向 Hermes 请求 LLM 推理。这允许 MCP 服务器让 Hermes 代表它生成文本——对于需要 LLM 能力但没有自己的模型访问权限的服务器很有用。

采样对所有 MCP 服务器默认启用（当 MCP SDK 支持时）。在 sampling 键下按服务器配置：

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # 启用采样（默认：true）
      model: "openai/gpt-4o"  # 覆盖采样请求的模型（可选）
      max_tokens_cap: 4096     # 每次采样响应的最大 Token 数（默认：4096）
      timeout: 30              # 每次请求的超时秒数（默认：30）
      max_rpm: 10              # 速率限制：每分钟最大请求数（默认：10）
      max_tool_rounds: 5       # 采样循环中的最大工具使用轮次（默认：5）
      allowed_models: []       # 服务器可请求的模型名称白名单（空 = 任意）
      log_level: "info"        # 审计日志级别：debug、info 或 warning（默认：info）

采样处理程序包含滑动窗口速率限制器、每请求超时和工具循环深度限制，以防止失控使用。指标（请求计数、错误、使用的 Token）按服务器实例跟踪。

要为特定服务器禁用采样：

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

将 Hermes 作为 MCP 服务器运行

除了连接到 MCP 服务器，Hermes 还可以作为 MCP 服务器。这让其他支持 MCP 的 Agent（Claude Code、Cursor、Codex 或任何 MCP 客户端）使用 Hermes 的消息功能——列出对话、阅读消息历史，以及在所有已连接平台上发送消息。

何时使用

你想让 Claude Code、Cursor 或其他编程 Agent 通过 Hermes 发送和阅读 Telegram/Discord/Slack 消息
你想要一个 MCP 服务器同时桥接到 Hermes 所有已连接的消息平台
你已经有一个运行中的 Hermes Gateway 和已连接的平台

快速开始

hermes mcp serve

这会启动一个 stdio MCP 服务器。MCP 客户端（而不是你）管理进程生命周期。

MCP 客户端配置

将 Hermes 添加到你的 MCP 客户端配置。例如，在 Claude Code 的 ~/.claude/claude_desktop_config.json 中：

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

或者如果你在特定位置安装了 Hermes：

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

可用工具

MCP 服务器暴露 10 个工具，匹配 OpenClaw 的频道桥接接口以及一个 Hermes 特有的频道浏览器：

工具	描述
conversations_list	列出活跃的消息对话。可按平台过滤或按名称搜索。
conversation_get	通过会话键获取一个对话的详细信息。
messages_read	阅读对话的最近消息历史。
attachments_fetch	从特定消息中提取非文本附件（图片、媒体）。
events_poll	从游标位置轮询新的对话事件。
events_wait	长轮询/阻塞直到下一个事件到达（近实时）。
messages_send	通过平台发送消息（例如 telegram:123456、discord:#general）。
channels_list	列出所有平台上可用的消息目标。
permissions_list_open	列出在此桥接会话期间观察到的待审批请求。
permissions_respond	允许或拒绝待审批请求。

事件系统

MCP 服务器包含一个实时事件桥接，轮询 Hermes 的会话数据库以获取新消息。这为 MCP 客户端提供了对传入对话的近实时感知：

# 轮询新事件（非阻塞）
events_poll(after_cursor=0)

# 等待下一个事件（阻塞直到超时）
events_wait(after_cursor=42, timeout_ms=30000)

事件类型：message、approval_requested、approval_resolved

事件队列是内存中的，在桥接连接时启动。较旧的消息可通过 messages_read 获取。

选项

hermes mcp serve              # 正常模式
hermes mcp serve --verbose    # 在 stderr 上输出调试日志

工作原理

MCP 服务器直接从 Hermes 的会话存储（~/.hermes/sessions/sessions.json 和 SQLite 数据库）读取对话数据。后台线程轮询数据库以获取新消息并维护内存中的事件队列。对于发送消息，它使用与 Hermes Agent 本身相同的 send_message 基础设施。

Gateway 不需要为读取操作运行（列出对话、阅读历史、轮询事件）。但需要为发送操作运行，因为平台适配器需要活动连接。

当前限制

仅支持 Stdio 传输（尚不支持 HTTP MCP 传输）
事件轮询间隔约 200ms，通过 mtime 优化的数据库轮询（文件未更改时跳过工作）
尚不支持 claude/channel 推送通知协议
仅文本发送（不能通过 messages_send 发送媒体/附件）

继续探索

这不是课程式的上一篇下一篇，而是从当前节点向外继续漫游。

教程与指南

使用 MCP

本指南展示如何在实际日常工作流中使用 MCP 与 Hermes Agent。如果说功能页面解释了 MCP 是什么，那么本指南则是关于如何快速、安全地从中获取价值。在以下情况使用 MCP：已有 MCP 形式的工具，且你不想自己构建 Hermes 原生工具你想让 Hermes 通过干净的 RPC 层操作本地或远程系

参考

CLI 命令参考

本页介绍从终端运行的命令行命令。聊天内斜杠命令请参见斜杠命令参考。 hermes [全局选项] <命令 [子命令/选项] hermes chat [options] 常用选项：示例： hermes hermes chat -q "总结最新的 PR" hermes chat --provider openrout

参考

斜杠命令参考

原文链接：Slash Commands Reference Hermes 有两个斜杠命令(Slash Command)界面，均由 hermes cli/commands.py 中的中央 COMMAND REGISTRY 驱动：交互式 CLI(命令行界面) 斜杠命令 — 由 cli.py 分发，支持从注册表自动补全

参考

常见问题与故障排除

常见问题和疑问的快速解答与修复方法。 Hermes Agent 兼容任何 OpenAI 兼容的 API。支持的提供商包括： OpenRouter ——通过一个 API 密钥访问数百个模型（推荐，灵活性最高） Nous Portal ——Nous Research 自有的推理端点 OpenAI ——GPT-4o、o1、o

核心功能

工具与工具集 (Tools & Toolsets)

Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform.

核心功能

记忆系统 (Memory System)

Hermes Agent has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it h

Core Features

核心功能

Hermes 的能力核心：工具、记忆、技能、委派、自动化、语音、插件与浏览器控制。

31 篇文档30 个节点

当前节点

MCP 集成 (MCP Integration)

返回分馆回到知识引擎

同主题继续探索

工具与工具集 (Tools & Toolsets)

Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform.

记忆系统 (Memory System)

Hermes Agent has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it h

技能系统 (Skill System)

技能是 Hermes 的可复用知识模块。每个技能都是一个 Markdown 文件，在激活时注入到 Agent 的上下文中——为其提供持久的工作流、领域知识和行为指南，而无需将这些内容塞入系统提示中。技能是可热插拔的：你可以在会话中途安装、创建、编辑和切换技能。它们在 CLI、消息平台和 Gateway 后台任务中均可

ACP 编辑器集成 (ACP Editor Integration)

Hermes Agent 可以作为 ACP 服务器运行，让 ACP 兼容的编辑器通过 stdio 与 Hermes 通信，并渲染： - 聊天消息 - 工具活动 - 文件差异 - 终端命令 - 审批提示 - 流式思考 / 响应片段当你希望 Hermes 像编辑器原生的编程 Agent 一样工作，而不是独立的 CLI 或

API 服务器 (API Server)

The API server exposes hermes-agent as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextCha

Honcho 记忆 (Honcho Memory)

Honcho is an AI-native memory backend that adds dialectic reasoning and deep user modeling on top of Hermes's built-in memory system. Instead of simple key-valu

MCP 集成 (MCP Integration)

MCP 提供的功能

快速开始

两种 MCP 服务器

Stdio 服务器

HTTP 服务器

基本配置参考

常用键

最小 stdio 示例

最小 HTTP 示例

Hermes 如何注册 MCP 工具

MCP 实用工具

重要说明

每服务器过滤

完全禁用服务器

白名单服务器工具

黑名单服务器工具

优先级规则

同时过滤实用工具

完整示例

如果所有工具都被过滤掉会怎样？

运行时行为

发现时间

动态工具发现

重新加载

工具集

安全模型

Stdio 环境过滤

配置级别的暴露控制

示例用例

带最小 Issue 管理的 GitHub 服务器

移除危险操作的 Stripe 服务器

单项目根目录的文件系统服务器

故障排除

MCP 服务器未连接

工具未出现

为什么资源或提示实用工具没有出现？

MCP 采样支持

将 Hermes 作为 MCP 服务器运行

何时使用

快速开始

MCP 客户端配置

可用工具

事件系统

选项

工作原理

当前限制

相关文档

继续探索

使用 MCP

CLI 命令参考

斜杠命令参考

常见问题与故障排除

工具与工具集 (Tools & Toolsets)

记忆系统 (Memory System)

核心功能

知识引擎 AI 问答