MCP（模型上下文协议）

MCP 允许 Hermes Agent 连接到外部工具服务器，从而使代理能够使用位于 Hermes 之外的工具——例如 GitHub、数据库、文件系统、浏览器栈、内部 API 等。

如果你曾希望 Hermes 能够使用某个已存在于其他位置的工具，MCP 通常是实现这一目标最简洁的方式。

MCP 提供的功能

• 无需先编写原生 Hermes 工具即可访问外部工具生态系统
• 在同一配置中同时支持本地 stdio 服务器和远程 HTTP MCP 服务器
• 启动时自动发现并注册工具
• 当服务器支持时，提供对 MCP 资源和提示的实用封装
• 每个服务器的过滤功能，可仅向 Hermes 暴露你真正希望其使用的 MCP 工具

快速入门

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

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

2. 将一个 MCP 服务器添加到 ~/.hermes/config.yaml：

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

3. 启动 Hermes：

hermes chat

4. 要求 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 服务器的场景包括：

• 服务器已本地安装
• 你需要对本地资源实现低延迟访问
• 你遵循的 MCP 服务器文档中展示了 command、args 和 env

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	string	stdio MCP 服务器的可执行文件
args	list	传递给 stdio 服务器的参数
env	mapping	传递给 stdio 服务器的环境变量
url	string	HTTP MCP 端点
headers	mapping	远程服务器的 HTTP 头信息
timeout	number	工具调用超时时间（秒）
connect_timeout	number	初始连接超时时间（秒）
enabled	bool	若为 false，Hermes 将完全跳过该服务器
tools	mapping	每个服务器的工具过滤和实用策略

最小 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

重要提示

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

• 仅当 MCP 会话确实支持资源操作时，Hermes 才会注册资源相关工具
• 仅当 MCP 会话确实支持提示操作时，Hermes 才会注册提示相关工具

因此，一个仅暴露可调用工具但不支持资源或提示的服务器，将不会获得这些额外的封装工具。

每服务器过滤

你可以控制每个 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 加上一个安全基线环境变量。这有助于减少意外的密钥泄露。

配置级别暴露控制

新的过滤支持也作为安全控制手段：

• 禁用你不希望模型看到的危险工具
• 为敏感服务器仅暴露最小白名单
• 在不希望暴露该接口时，禁用资源/提示词包装器

示例用例

仅提供最小化问题管理功能的 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 服务器无法连接

请检查：

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

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

工具未出现

可能原因包括：

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

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

为何资源或提示词工具未出现？

因为 Hermes 现在仅在以下两个条件同时满足时才会注册这些包装器：

1. 你的配置允许注册
2. 服务器会话确实支持该功能

这是有意为之的设计，以确保工具列表的真实性。

MCP 采样支持

MCP 服务器可通过 sampling/createMessage 协议向 Hermes 请求 LLM 推理。这使得 MCP 服务器可以请求 Hermes 代为生成文本 —— 对于需要 LLM 能力但自身无模型访问权限的服务器非常有用。

采样功能默认启用（当 MCP SDK 支持时）。可按服务器在 sampling 键下进行配置：

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Enable sampling (default: true)
      model: "openai/gpt-4o"  # Override model for sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens per sampling response (default: 4096)
      timeout: 30              # Timeout in seconds per request (default: 30)
      max_rpm: 10              # Rate limit: max requests per minute (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds in sampling loops (default: 5)
      allowed_models: []       # Allowlist of model names the server may request (empty = any)
      log_level: "info"        # Audit log level: debug, info, or warning (default: info)

采样处理器包含滑动窗口速率限制、每请求超时机制以及工具循环深度限制，以防止资源滥用。每个服务器实例的指标（请求次数、错误数、使用 token 数）均被追踪。

如需禁用特定服务器的采样功能：

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

以 MCP 服务器身份运行 Hermes

除了连接 到 MCP 服务器外，Hermes 本身也可以 作为 一个 MCP 服务器运行。这使得其他具备 MCP 能力的代理（如 Claude Code、Cursor、Codex 或任何 MCP 客户端）能够使用 Hermes 的消息功能 —— 包括列出对话、读取消息历史记录，并跨所有已连接平台发送消息。

何时使用此功能

• 你希望 Claude Code、Cursor 或其他编程代理通过 Hermes 发送和接收 Telegram/Discord/Slack 消息
• 你希望有一个单一的 MCP 服务器，能够同时桥接到 Hermes 所有已连接的消息平台
• 你已运行一个带有已连接平台的 Hermes 网关

快速入门

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 客户端能够近乎实时地感知到新收到的会话：

# Poll for new events (non-blocking)
events_poll(after_cursor=0)

# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)

事件类型：message、approval_requested、approval_resolved

事件队列为内存中存储，桥接连接启动时开始运行。较旧的消息可通过 messages_read 获取。

选项

hermes mcp serve              # Normal mode
hermes mcp serve --verbose    # Debug logging on stderr

工作原理

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

对于读操作（列出会话、读取消息历史、轮询事件），网关无需运行。但发送消息时，网关必须运行，因为平台适配器需要保持活跃连接。

当前限制

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

相关文档

• 使用 MCP 与 Hermes
• CLI 命令
• 斜杠命令
• 常见问题