use mcp with hermes — The Hermes Bible

本指南說明如何在日常工作中實際使用 MCP 與 Hermes Agent。

如果功能頁面解釋了 MCP 是什麼，本指南則是關於如何快速且安全地從中獲得價值。

何時應該使用 MCP？

使用 MCP 的情境：

某個工具已經以 MCP 形式存在，而你不想建立原生 Hermes 工具
你想讓 Hermes 透過乾淨的 RPC 層操作本地或遠端系統
你想對每個伺服器進行細粒度的曝露控制
你想將 Hermes 連接到內部 API、資料庫或公司系統，而無需修改 Hermes 核心

不使用 MCP 的情境：

內建的 Hermes 工具已經能很好地完成工作
伺服器曝露了大量危險的工具介面，而你沒有準備好進行過濾
你只需要一個非常窄的整合，而原生工具會更簡單、更安全

心智模型

將 MCP 想像成一個適配器層：

Hermes 仍然是代理
MCP 伺服器貢獻工具
Hermes 在啟動或重新載入時發現這些工具
模型可以像使用普通工具一樣使用它們
你控制每個伺服器的可見程度

最後一點很重要。良好的 MCP 使用不是「連接所有東西」，而是「連接正確的東西，使用最小的有用介面」。

步驟 1：安裝 MCP 支援

如果你使用標準安裝腳本安裝了 Hermes，MCP 支援已經包含在內（安裝程式會執行 uv pip install -e ".[all]"）。

如果你安裝時沒有包含 extras 並需要單獨添加 MCP：

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

對於基於 npm 的伺服器，請確保 Node.js 和 npx 可用。

對於許多 Python MCP 伺服器，uvx 是一個不錯的預設選擇。

步驟 2：先添加一個伺服器

從一個單獨、安全的伺服器開始。

範例：僅對一個專案目錄進行檔案系統存取。

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

然後啟動 Hermes：

hermes chat

現在問一些具體的問題：

Inspect this project and summarize the repo layout.

步驟 3：驗證 MCP 已載入

你可以透過幾種方式驗證 MCP：

Hermes 橫幅/狀態應在設定時顯示 MCP 整合
詢問 Hermes 它有哪些可用工具
設定變更後使用 /reload-mcp
如果伺服器連接失敗，請檢查日誌

實用的測試提示：

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

步驟 4：立即開始過濾

如果伺服器曝露了大量工具，不要等到以後再過濾。

範例：只白名單你想要的

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 核心的瀏覽器傳輸

建議的伺服器

使用 chrome-devtools-mcp。

如果你的 Windows Chrome 已經從 chrome://inspect/#remote-debugging 啟用了即時遠端除錯，請從 WSL 這樣新增：

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

儲存伺服器後：

hermes mcp test chrome-devtools-win

然後啟動一個新的 Hermes 會話或執行：

/reload-mcp

典型提示

載入後，Hermes 可以直接使用 MCP 前綴的瀏覽器工具。例如：

調用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出當前瀏覽器標籤頁。

當 `/browser connect` 不是正確工具時

如果 Hermes 在 WSL 中運行，而 Chrome 在 Windows 上運行，即使 Chrome 已開啟且可除錯，/browser connect 也可能失敗。

常見原因：

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 中的背景/凍結標籤頁數量並重試。

範例：黑名單危險操作

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

範例：同時停用實用包裝器

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

過濾實際上會影響什麼？

Hermes 中有兩類 MCP 暴露的功能：

伺服器原生 MCP 工具

透過以下方式過濾：
- tools.include
- tools.exclude

Hermes 新增的實用包裝器

透過以下方式過濾：
- tools.resources
- tools.prompts

你可能會看到的實用包裝器

Resources：

list_resources
read_resource

Prompts：

list_prompts
get_prompt

這些包裝器僅在以下情況出現：

你的設定允許它們，且
MCP 伺服器會話實際支援這些功能

因此 Hermes 不會假裝一個伺服器有 resources/prompts，如果它實際沒有的話。

常見模式

模式 1：本地專案助手

使用 MCP 進行專案本地的檔案系統或 git 伺服器操作，當你想讓 Hermes 在一個有界的工作區中進行推理時。

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.

模式 2：GitHub 分類助手

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.

模式 3：內部 API 助手

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.

這是嚴格白名單比排除清單好得多的地方。

模式 4：文件/知識伺服器

某些 MCP 伺服器暴露的 prompts 或 resources 更像是共享的知識資產，而非直接操作。

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.

教學：帶過濾的端到端設定

這裡是一個實用的進階過程。

階段 1：新增帶有嚴格白名單的 GitHub MCP

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.

階段 2：僅在需要時擴展

如果你之後也需要 issue 更新：

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

然後重新載入：

/reload-mcp

階段 3：新增帶有不同策略的第二個伺服器

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
從尽可能小的集合開始

停用未使用的實用工具

如果你不希望模型瀏覽伺服器提供的 resources/prompts，請將它們關閉：

tools:
  resources: false
  prompts: false

保持伺服器範圍狹窄

範例：

檔案系統伺服器限定於一個專案目錄，而非你的整個主目錄
git 伺服器指向一個倉庫
內部 API 伺服器預設以讀取為主的工具曝露

設定變更後重新載入

/reload-mcp

在以下情況後執行此操作：

include/exclude 清單
已啟用的標誌
resources/prompts 開關
認證標頭/環境變數

依症狀排除問題

「伺服器已連接，但缺少我預期的工具」

可能原因：

被 tools.include 過濾
被 tools.exclude 排除
透過 resources: false 或 prompts: false 停用了實用包裝器
伺服器實際上不支援 resources/prompts

「伺服器已設定但什麼都沒有載入」

檢查：

設定中是否遺留了 enabled: false
命令/運行時是否存在（npx、uvx 等）
HTTP 端點是否可到達
認證環境變數或標頭是否正確

「為什麼我看到的工具比 MCP 伺服器宣稱的少？」

因為 Hermes 現在尊重你的每個伺服器策略和功能感知的註冊。這是預期的，通常也是期望的。

「如何在不刪除設定的情況下移除 MCP 伺服器？」

使用：

enabled: false

這會保留設定但阻止連接和註冊。

建議的初次 MCP 設定

大多數用戶的良好首個伺服器：

filesystem
git
GitHub
fetch / 文件 MCP 伺服器
一個窄範圍的內部 API

不太好的首個伺服器：

具有大量破壞性操作且無過濾的大型業務系統
你不夠了解以進行約束的任何東西

何時應該使用 MCP？

心智模型

步驟 1：安裝 MCP 支援

步驟 2：先添加一個伺服器

步驟 3：驗證 MCP 已載入

步驟 4：立即開始過濾

範例：只白名單你想要的

WSL2：將 WSL 中的 Hermes 橋接到 Windows Chrome

為什麼此模式有用

建議的伺服器

典型提示

當 `/browser connect` 不是正確工具時

已知陷阱

範例：黑名單危險操作

範例：同時停用實用包裝器

過濾實際上會影響什麼？

你可能會看到的實用包裝器

常見模式

模式 1：本地專案助手

模式 2：GitHub 分類助手

模式 3：內部 API 助手

模式 4：文件/知識伺服器

教學：帶過濾的端到端設定

階段 1：新增帶有嚴格白名單的 GitHub MCP

階段 2：僅在需要時擴展

階段 3：新增帶有不同策略的第二個伺服器

安全使用建議

對危險系統優先使用白名單

停用未使用的實用工具

保持伺服器範圍狹窄

設定變更後重新載入

依症狀排除問題

「伺服器已連接，但缺少我預期的工具」

「伺服器已設定但什麼都沒有載入」

「為什麼我看到的工具比 MCP 伺服器宣稱的少？」

「如何在不刪除設定的情況下移除 MCP 伺服器？」

建議的初次 MCP 設定

相關文件

在 Hermes 中使用語音模式

何時應該使用 MCP？

心智模型

步驟 1：安裝 MCP 支援

步驟 2：先添加一個伺服器

步驟 3：驗證 MCP 已載入

步驟 4：立即開始過濾

範例：只白名單你想要的

WSL2：將 WSL 中的 Hermes 橋接到 Windows Chrome

為什麼此模式有用

建議的伺服器

典型提示

當 /browser connect 不是正確工具時

已知陷阱

範例：黑名單危險操作

範例：同時停用實用包裝器

過濾實際上會影響什麼？

你可能會看到的實用包裝器

常見模式

模式 1：本地專案助手

模式 2：GitHub 分類助手

模式 3：內部 API 助手

模式 4：文件/知識伺服器

教學：帶過濾的端到端設定

階段 1：新增帶有嚴格白名單的 GitHub MCP

階段 2：僅在需要時擴展

階段 3：新增帶有不同策略的第二個伺服器

安全使用建議

對危險系統優先使用白名單

停用未使用的實用工具

保持伺服器範圍狹窄

設定變更後重新載入

依症狀排除問題

「伺服器已連接，但缺少我預期的工具」

「伺服器已設定但什麼都沒有載入」

「為什麼我看到的工具比 MCP 伺服器宣稱的少？」

「如何在不刪除設定的情況下移除 MCP 伺服器？」

建議的初次 MCP 設定

相關文件

在 Hermes 中使用語音模式

當 `/browser connect` 不是正確工具時