从一封催款邮件说起：Agent 需要两只手

你手上有个 Hermes Agent，能写文案、能总结报表。但你让它“查一下今天哪些订单超过 7 天没付款，然后给客户发提醒邮件”，它卡住了。LLM 没有手，它看不到你的 MySQL 里有什么数据，也没有发信通道。要让 Agent 真正干活，得给它接上工具。

MCP（Model Context Protocol）就是干这个的。Anthropic 在 2024 年底开源这套协议后，它成了 AI 工具调用的实际标准。Hermes Agent 从 0.4.0 开始内置 MCP 客户端，你可以把数据库、邮件、文件系统、HTTP API 都包装成 MCP 服务器，让 Agent 按需调用。

这篇教程用真实命令走一遍：装 Hermes Agent，接一个 MySQL MCP 服务器，再接一个 SMTP 邮件服务器，写一个技能让 Agent 自动完成“查库→发信”。环境是 Ubuntu 22.04，Python 3.11.6，Hermes 0.4.2。

需求拆成三件事。第一，让 Agent 能执行 SELECT 查询，从 orders 表捞数据。第二，让 Agent 能调 SMTP 发信，把提醒邮件发到客户邮箱。第三，把两个动作串成一个技能，定时跑。MCP 的架构不复杂：Agent 是客户端，MCP 服务器是工具提供方。每个服务器暴露一组工具，比如 mysql 服务器暴露 query 工具，smtp 服务器暴露 send_email 工具。Agent 收到你的自然语言指令后，自己决定调哪个工具、传什么参数。不需要你写代码控制流程。

好处是省事，坏处是工具调用失败时报错信息藏在进程日志里，排查比普通函数调用麻烦。后面我把常见坑都列出来。

装好 Hermes Agent，接上 MySQL 数据库

先装 Hermes。建议用虚拟环境，别怼到系统 Python 里。

python3 -m venv venv
source venv/bin/activate
pip install hermes-agent

装完确认版本：

hermes --version

输出应该是 hermes-agent 0.4.2 或更高。如果看到 0.3.x，是 pip 缓存了旧版，用 pip install --upgrade hermes-agent 强制更新。

MCP 服务器依赖 Node.js 18+。检查一下：

node --version

Ubuntu 22.04 自带 node 12.x，太旧，npx 跑不起来。从 nodesource 装 18.x：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Hermes 的配置文件在 ~/.hermes/config.yaml。默认不存在，先运行 hermes init 生成。然后注册 MySQL MCP 服务器。官方包名是 @modelcontextprotocol/server-mysql，用 npx 启动。在 config.yaml 里加：

mcp_servers:
  mysql:
    command: npx
    args:
      - -y
      - @modelcontextprotocol/server-mysql
    env:
      MYSQL_HOST: 127.0.0.1
      MYSQL_PORT: 3306
      MYSQL_USER: root
      MYSQL_PASS: "你的密码"
      MYSQL_DB: shop

env 的值都要是字符串。密码别用纯数字开头，YAML 会解析成整数导致连接失败。保存后跑：

hermes mcp list

正常输出里应该有 mysql 服务器，下面有 query 和 list_tables 两个工具。如果报错 ECONNREFUSED 127.0.0.1:3000，说明你写成了 SSE 地址，MCP 本地工具用 stdio 方式，配置里只写 command 和 args，不写 url。如果连接超时，是 npx 首次下载包太慢，先手动跑 npx -y @modelcontextprotocol/server-mysql --help 缓存包。

测试 Agent 查库：

hermes run "查一下 orders 表里 status='unpaid' 的记录数"

Agent 会调用 query 工具执行 SELECT count(*) FROM orders WHERE status='unpaid'。如果 Agent 说没权限查数据库，检查 YAML 缩进，mcp_servers 和 agent 是平级，别塞进别的段。

接上 SMTP，让 Agent 能发邮件

邮件这块没有官方 MCP 服务器，我用一个 Python 写的轻量 MCP 服务器，代码不到 50 行。建目录：

mkdir -p ~/.hermes/mcp-servers
cd ~/.hermes/mcp-servers

写 mail_server.py，核心逻辑是用 smtplib 发信，包装成 MCP 工具。关键片段：

from mcp.server import Server
from mcp.types import Tool
import smtplib
import os

app = Server("mail-server")

@app.list_tools()
async def list_tools():
    return [Tool(
        name="send_email",
        description="发送邮件，参数：to, subject, body",
        inputSchema={
            "type": "object",
            "properties": {
                "to": {"type": "string"},
                "subject": {"type": "string"},
                "body": {"type": "string"}
            },
            "required": ["to", "subject", "body"]
        }
    )]

实现函数里用 smtplib.SMTP_SSL 连服务器，端口 465。我这里用 QQ 邮箱 SMTP：smtp.qq.com，端口 465。QQ 邮箱不能用登录密码，要在设置里开启 SMTP 服务，生成 16 位授权码。call_tool 函数里，先构建 MIMEText 对象，再 SMTP_SSL 连接、login、sendmail。

在 config.yaml 里注册：

  mail:
    command: python3
    args:
      - /home/你的用户名/.hermes/mcp-servers/mail_server.py
    env:
      SMTP_HOST: smtp.qq.com
      SMTP_PORT: "465"
      SMTP_USER: "你的邮箱@qq.com"
      SMTP_PASS: "你的16位授权码"

测试发信：

hermes run "给 test@example.com 发一封测试邮件，主题是 MCP 测试，正文写 你好"

常见报错一：

smtplib.SMTPAuthenticationError: (535, b'login fail')

授权码不对或 SMTP 服务没开。去邮箱设置里确认。常见报错二：

smtplib.SMTPConnectError: (421, b'connect to smtp.qq.com timeout')

网络问题。海外服务器连 QQ 邮箱经常超时，换 SendGrid 或阿里云邮件推送，改 SMTP_HOST 和端口就行。

还有个小坑：Agent 生成的正文可能带 \n 转义字符而不是真换行，邮件显示成一行。在实现里加 body.replace("\\n", "\n") 解决。

写个技能，把查库和发信串起来

工具都通了，写一个技能把“查未付款订单→生成提醒邮件→发信”串起来。技能文件放 ~/.hermes/skills/，YAML 格式。我建 dunning.yml：

name: dunning
description: 查询未付款订单并发送催款邮件
steps:
  - action: tool
    server: mysql
    tool: query
    params:
      sql: "SELECT id, customer_email, amount FROM orders WHERE status='unpaid' AND created_at < NOW() - INTERVAL 7 DAY"
  - action: loop
    for_each: row
    steps:
      - action: tool
        server: mail
        tool: send_email
        params:
          to: "{{ row.customer_email }}"
          subject: "订单 {{ row.id }} 付款提醒"
          body: "您好，您的订单 {{ row.id }} 金额 {{ row.amount }} 元已逾期 7 天，请尽快付款。"

这是简化写法，实际 Hermes 技能格式略有差异，但结构是这样。加载技能：

hermes skill load dunning

手动跑一次：

hermes run "执行 dunning 技能"

你会看到 Agent 先调 mysql 的 query 工具，拿到结果后逐条调 mail 的 send_email。日志会打印每次工具调用的参数和返回。有个翻车点：数据库里 amount 是 Decimal 类型，转字符串会变成 Decimal('99.00')。在技能里加一步清洗，或让 Agent 用 round(float(amount), 2) 处理。

用 memory 命令记录客户信息，方便后续跟进：

hermes memory add --key customer_1001 --value "王总，订单 1001 逾期 9 天，已发两次提醒，电话 13800138000"
hermes memory get customer_1001

记忆存在 ~/.hermes/memory/ 下的 SQLite 里，重启不丢。

手动跑通后上定时任务：

hermes cron create --name dunning_daily --schedule "0 9 * * *" --skill dunning

每天早上 9 点执行。如果没触发，查时区。Hermes 默认 UTC，你写 0 9 实际是北京时间下午 5 点。在 config.yaml 里设：

timezone: Asia/Shanghai

改完重启 hermes 服务生效。查看任务列表用 hermes cron list，删任务用 hermes cron delete dunning_daily。

常见报错和排查清单

按频率排序，对照排查。

第一位：MCP 服务器启动超时。症状是 hermes mcp list 卡住，或 Agent 说“工具不可用”。原因是 npx 首次下载包太慢。手动 npx 跑一次缓存包，或用国内镜像：

npm config set registry https://registry.npmmirror.com

第二位：工具参数类型不匹配。Agent 调用 send_email 时把 to 传成数组，MCP 校验失败：

Error: Invalid params: to must be string

在 inputSchema 的 description 里写清楚“收件人邮箱，必须是单个字符串，不要传数组”，能显著减少这类错误。

第三位：MySQL 查询结果太大。几十万行数据拉回来，MCP 传输层内存溢出。技能里 SQL 加 LIMIT 100，或让 Agent 先做聚合统计。

第四位：发信频率限制。QQ 邮箱每天有上限，超了返回 550 错误：

smtplib.SMTPDataError: (550, b'Daily limit exceeded')

只能等第二天，或换企业邮箱服务。生产环境用阿里云邮件推送，单日配额 1000 封。

第五位：YAML 语法错误。最常见是缩进不对或密码含冒号没加引号。Hermes 启动时报：

yaml.parser.ParserError: while parsing a block mapping

用 python3 -c "import yaml; yaml.safe_load(open('/root/.hermes/config.yaml'))" 检查语法。

日志在 ~/.hermes/logs/ 目录，按日期滚动。MCP 服务器输出以子进程日志记录。排查时先 tail：

tail -f ~/.hermes/logs/hermes.log

另外提醒一句：MCP 工具给了 Agent 执行能力，权限要收紧。MySQL 账号只给 SELECT 权限，别用 root。SMTP 授权码单独申请。这样即使 Agent 被提示词注入攻击，破坏范围也有限。

💬 你用过哪些AI工具？

这套 MCP 配置你跑通了吗？我花了整整一个下午才搞定 SMTP 授权码的坑，后来发现是 QQ 邮箱设置里没开“允许弱密码登录”。你平时给 Agent 配过哪些工具？数据库、邮件还是爬虫？配 MCP 时遇到最离谱的报错是什么？

如果你在选模型搭 Agent，可以去 AI House 排行榜（aibunkhouse.com/rankings/）看看最新模型排名，上面有社区实时投票。你用的 Claude、GPT、文心、通义都在榜上，给用得顺手的模型投一票，帮其他人少走弯路。

常见问题 / FAQ

从一封催款邮件说起：Agent 需要两只手

你手上有个 Hermes Agent，能写文案、能总结报表。但你让它“查一下今天哪些订单超过 7 天没付款，然后给客户发提醒邮件”，它卡住了。LLM 没有手，它看不到你的 MySQL 里有什么数据，也没有发信通道。要让 Agent 真正干活，得给它接上工具。 MCP（Model Context Protocol）就是干这个的。Anthropic 在 2024 年底开源这套协议后，它成了 AI...

装好 Hermes Agent，接上 MySQL 数据库

先装 Hermes。建议用虚拟环境，别怼到系统 Python 里。 python3 -m venv venv source venv/bin/activate pip install hermes-agent 装完确认版本： hermes --version 输出应该是 hermes-agent 0.4.2 或更高。如果看到 0.3.x，是 pip 缓存了旧版，用 pip instal...

接上 SMTP，让 Agent 能发邮件

邮件这块没有官方 MCP 服务器，我用一个 Python 写的轻量 MCP 服务器，代码不到 50 行。建目录： mkdir -p ~/.hermes/mcp-servers cd ~/.hermes/mcp-servers 写 mail_server.py，核心逻辑是用 smtplib 发信，包装成 MCP 工具。关键片段： from mcp.server import Server ...

写个技能，把查库和发信串起来

工具都通了，写一个技能把“查未付款订单→生成提醒邮件→发信”串起来。技能文件放 ~/.hermes/skills/，YAML 格式。我建 dunning.yml： name: dunning description: 查询未付款订单并发送催款邮件 steps: - action: tool server: mysql tool: query params: ...

常见报错和排查清单

按频率排序，对照排查。 第一位：MCP 服务器启动超时。症状是 hermes mcp list 卡住，或 Agent 说“工具不可用”。原因是 npx 首次下载包太慢。手动 npx 跑一次缓存包，或用国内镜像： npm config set registry https://registry.npmmirror.com 第二位：工具参数类型不匹配。Agent 调用 send_email ...