教程概述

系列索引: Hermes Agent 教程系列

何时需要读这篇：如果你想为 Hermes 接入自定义工具、连接外部 API，或者扩展数据库访问、网页抓取、文件系统操作等能力，就该读这一篇。

本文介绍 Hermes Agent 的MCP 集成，也就是通过 Model Context Protocol 来扩展能力。

你将学到什么

• ✅ MCP 是什么，以及为什么重要
• ✅ Hermes 对 MCP 的支持架构
• ✅ 如何把 MCP 服务器接入 Hermes
• ✅ 常见 MCP 集成方式
• ✅ 自定义 MCP 开发基础

什么是 MCP？

Model Context Protocol

MCP（Model Context Protocol）是一种开放标准，用于把 AI 模型连接到外部工具与数据源。它提供：

• 标准化接口 — 所有工具都使用统一接入方式
• 发现机制 — 模型可以发现可用工具
• 安全边界 — 对资源访问进行受控隔离

flowchart TD
    A[AI 模型] --> B[MCP 客户端]
    B --> C[MCP Server 1: 数据库]
    B --> D[MCP Server 2: 文件]
    B --> E[MCP Server 3: Web]
    B --> F[MCP Server N: 自定义]

    C --> G[工具: query, insert]
    D --> H[工具: read, write]
    E --> I[工具: fetch, search]
    F --> J[工具: custom]

    style B fill:#e1f5ff
    style G fill:#fff3e0

为什么 MCP 很重要

如果没有 MCP，每接一个工具都要写专门的集成层；有了 MCP：

Hermes 的 MCP 支持

架构

Hermes 内置了一个 MCP 客户端，会自动发现并连接已配置的服务器：

flowchart LR
    A[Hermes Agent] --> B[MCP Client]
    B --> C[Server Registry]
    C --> D[SQLite MCP]
    C --> E[Filesystem MCP]
    C --> F[Brave Search MCP]
    C --> G[Custom MCP]

    D --> H[工具调用]
    E --> H
    F --> H
    G --> H

    H --> A

    style B fill:#e1f5ff

配置位置

MCP 服务器通常配置在：

~/.hermes/mcp/
├── config.json          # 服务器注册表
├── servers/             # 已安装的服务器二进制
└── logs/                # MCP 通信日志

添加 MCP 服务器

配置格式

把服务器加入 ~/.hermes/mcp/config.json：

{
  "servers": {
    "sqlite": {
      "command": "mcp-server-sqlite",
      "args": ["--db-path", "/data/mydb.sqlite"],
      "env": {}
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "/workspace"],
      "env": {}
    },
    "brave-search": {
      "command": "mcp-server-brave-search",
      "args": [],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

通过 CLI 配置

# 添加 MCP 服务器
hermes mcp add sqlite --command "mcp-server-sqlite" --args "--db-path /data/mydb.sqlite"

# 查看已配置服务器
hermes mcp list

# 测试服务器连接
hermes mcp test sqlite

在 Hermes 中使用 MCP 工具

配置完成后，Hermes 就可以调用 MCP 工具：

你: 查询本周新增的用户

Hermes: 正在使用 sqlite MCP...
[Tool: sqlite.query]
SELECT * FROM users WHERE created_at > '2026-04-06';
Result: 15 users found

Hermes: 这周共新增了 15 个用户……

常见 MCP 集成

File System MCP

在受控边界内访问文件系统：

hermes mcp add filesystem --command "mcp-server-filesystem" --args "--root ~/workspace"

提供的工具：

• read_file — 读取文件内容
• write_file — 创建或修改文件
• list_directory — 列出目录内容
• search_files — 按模式查找文件

SQLite MCP

查询 SQLite 数据库：

hermes mcp add sqlite --command "mcp-server-sqlite" --args "--db-path /data/analytics.sqlite"

提供的工具：

• query — 执行 SQL 查询
• list_tables — 查看表结构
• describe_table — 查看字段细节

Brave Search MCP

通过 Brave API 做网页搜索：

hermes mcp add brave-search --command "mcp-server-brave-search" --env BRAVE_API_KEY=YOUR_KEY

提供的工具：

• search — 网页搜索
• search_news — 新闻搜索

GitHub MCP

面向 GitHub 仓库操作：

hermes mcp add github --command "mcp-server-github" --env GITHUB_TOKEN=YOUR_TOKEN

提供的工具：

• search_repositories
• get_file_contents
• create_issue
• list_commits

Slack MCP

与 Slack 工作区集成：

hermes mcp add slack --command "mcp-server-slack" --env SLACK_BOT_TOKEN=YOUR_TOKEN

提供的工具：

• send_message
• list_channels
• get_channel_history

MCP 服务器目录

浏览可用服务器：

hermes mcp catalog

输出示例：

Server               Category      Tools
─────────────────────────────────────────────────
filesystem           Files         4
sqlite               Database      3
postgres             Database      5
brave-search         Web           2
github               Development   8
slack                Communication 4
google-drive         Files         6
puppeteer            Browser       5
fetch                HTTP          3

自定义 MCP 开发

MCP 服务器的基础能力

一个 MCP 服务器通常需要实现：

1. Discovery — 列出可用工具
2. Execution — 响应工具调用
3. Schema — 定义输入输出类型

最小 MCP 服务器示例（Python）

from mcp.server import Server
from mcp.types import Tool, ToolResult

server = Server("my-custom-mcp")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="hello",
            description="Say hello",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"}
                },
                "required": ["name"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "hello":
        return ToolResult(
            content=f"Hello, {arguments['name']}!"
        )

server.run()

部署自定义 MCP

# 安装依赖
pip install mcp

# 运行服务器
python my_mcp_server.py

# 配置到 Hermes
hermes mcp add my-custom --command "python my_mcp_server.py"

MCP 服务器最佳实践

1. 工具命名清晰 — 推荐使用 verb_noun 格式
2. Schema 明确 — 定义所有参数
3. 错误处理清楚 — 返回可理解的错误信息
4. 安全检查完善 — 执行前验证输入

安全注意事项

工具权限

配置 Hermes 允许使用哪些工具：

mcp:
  permissions:
    filesystem:
      read_file: allow
      write_file: approval_required
    sqlite:
      query: allow
      insert: deny

审批流程

对于 approval_required 类型工具：

sequenceDiagram
    participant U as 用户
    participant H as Hermes
    participant M as MCP Server

    H->>U: 该工具需要审批: write_file
    U->>H: 批准
    H->>M: 执行 write_file
    M->>H: 返回结果
    H->>U: 完成

    style U fill:#fff3e0

常见问题排查

MCP 服务器未找到

原因：服务器二进制没有安装。

解决方案：

# 安装服务器
pip install mcp-server-sqlite

# 或通过 npm 安装
npm install @anthropic-ai/mcp-server-filesystem

工具调用失败

原因：Schema 不匹配，或权限被拒绝。

解决方案：

hermes mcp test SERVER_NAME
hermes mcp logs SERVER_NAME

环境变量未设置

原因：MCP 服务器依赖 API key。

解决方案：

hermes mcp edit brave-search --env BRAVE_API_KEY=YOUR_KEY

总结

MCP 集成提供了强扩展能力：

1. 标准协议 — 所有工具共用同一套接口
2. 配置简单 — 可用 JSON 或 CLI 配置
3. 常见服务器丰富 — 文件、数据库、网页、GitHub 等都有
4. 可自定义开发 — 你可以自己构建 MCP 服务器
5. 安全控制 — 权限与审批机制保护敏感操作

关键要点

• ✅ MCP 是工具集成的开放标准
• ✅ Hermes 内置了 MCP 客户端用于发现与调用
• ✅ 常见服务器已经覆盖很多高频场景
• ✅ 自定义服务器可以进一步扩展 Hermes
• ✅ 安全控制能保护敏感操作

系列导航:

• ← 上一篇: 教程 8：cron 调度 — 自动化与定时报告
• 返回: 系列索引

毕业里程碑 G3：完成本文，也就是整个系列的最后一篇后，你已经达到大师级别。此时你的 Hermes Agent 已完成 MCP 扩展、自定义技能、多平台部署以及无服务器后端集成，成为一个完整且可扩展的 AI 助手平台。