MCP（模型上下文協議）

MCP 允許 Hermes Agent 連接到外部工具服務器，從而使 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 服務器無法連接

請檢查：

# 驗證 MCP deps 是否已安裝（已包含在標準安裝中）
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            # 啟用採樣（默認值：true）
      model: "openai/gpt-4o"  # 覆蓋 model 採樣請求（可選）
      max_tokens_cap: 4096     # 每個採樣響應的最大 tokens（默認值：4096）
      timeout: 30              # 每個請求的超時秒數（默認值：30）
      max_rpm: 10              # 速率限制：每分鐘最大請求數（默認值：10）
      max_tool_rounds: 5       # 最大 tool - 採樣循環中使用輪數（默認值：5）
      allowed_models: []       # 服務器可能請求的 model 名稱白名單（空 = 任意）
      log_level: "info"        # 審核日誌級別：調試、信息或警告（默認：信息）

採樣處理器包含滑動窗口速率限制、每請求超時機制以及工具循環深度限制，以防止資源濫用。每個服務器實例的指標（請求次數、錯誤數、使用 token 數）均被追蹤。

如需禁用特定服務器的採樣功能：

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

以 MCP 服務器身份運行 Hermes

除了連接 到 MCP 服務器外，Hermes 本身也可以 作為 一個 MCP 服務器運行。這使得其他具備 MCP 能力的 Agent（如 Claude Code、Cursor、Codex 或任何 MCP 客戶端）能夠使用 Hermes 的消息功能 —— 包括列出對話、讀取消息歷史記錄，並跨所有已連接平臺發送消息。

何時使用此功能

• 你希望 Claude Code、Cursor 或其他編程 Agent 通過 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 客戶端能夠近乎實時地感知到新收到的會話：

# 輪詢新事件（非阻塞）
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 基礎設施。

對於讀操作（列出會話、讀取消息歷史、輪詢事件），網關無需運行。但發送消息時，網關必須運行，因為平臺適配器需要保持活躍連接。

當前限制

• 僅支持 Stdio 傳輸（尚未支持 HTTP MCP 傳輸）
• 事件輪詢間隔約為 200ms，通過 mtime 優化的數據庫輪詢實現（文件未更改時跳過工作）
• 尚未支持 claude/channel 推送通知協議
• 僅支持文本發送（通過 messages_send 無法發送媒體/附件）

相關文檔

• 使用 MCP 與 Hermes
• CLI 命令
• 斜槓命令
• 常見問題