Hermes 的 MCP Server 模式是一个反向集成：不是用 Claude Code 调用工具，而是 Hermes 把自己的消息数据（Telegram / Discord / Slack 等多平台的会话历史）暴露为 MCP 工具，让 Claude Code 或任意 MCP 客户端来消费。核心价值是「跨平台消息整合」——在 Claude Code 里直接读 Telegram 群里的讨论记录，不需要切换 App。

Hermes Agent MCP Server 模式：让 Claude Code 读取你的 Telegram / Discord 消息记录

为什么需要这个功能

典型场景：你的团队在 Telegram 群里讨论技术方案，你想用 Claude Code 帮你分析这些讨论并写成文档。正常流程需要手动复制消息——Hermes MCP Server 模式让这个过程可以自动化：

1. Hermes 作为 MCP Server 运行，挂载在 Claude Code 里
2. Claude Code 调用 messages_read 工具，传入 Telegram 会话 ID
3. 读取最近 50 条消息，直接在上下文里处理

这是 Hermes 独有的反向集成能力——在开源 AI Agent 里，把多平台消息数据暴露为 MCP 接口的，目前只有 Hermes。

暴露的 10 个工具

Hermes MCP Server 暴露的工具和 OpenClaw 的 9 工具接口对齐，额外增加 1 个 Hermes 特有工具：

工具名	功能
conversations_list	列出所有活跃会话（跨平台）
conversation_get	获取指定会话详情
messages_read	读取会话消息历史（可指定条数和时间范围）
attachments_fetch	获取消息里的附件（图片、文件）
events_poll	轮询新事件（非阻塞）
events_wait	等待新事件（阻塞，最多 N 秒）
messages_send	通过 Hermes 发送消息到指定平台
permissions_list_open	列出待审批操作
permissions_respond	响应审批请求（批准/拒绝）
channels_list	列出所有可访问的频道（Hermes 特有）

MCP Server 读取的数据来自 Hermes 本地的 SQLite SessionDB（~/.hermes/state.db），不直接连接消息平台——数据由 Hermes Gateway 写入，MCP Server 只是读取。所以必须先部署好 Hermes Gateway，MCP Server 才有数据可读。

配置 Claude Code 使用 Hermes MCP Server

第一步：确保 Hermes Gateway 在运行

# 后台启动 Telegram Gateway（需要先配好 TELEGRAM_BOT_TOKEN）
hermes gateway telegram &

或者用 systemd / supervisor 管理进程，保证开机自启。

第二步：在 Claude Code 里配置 MCP Server

在 Claude Code 的 MCP 配置文件里添加 Hermes：

全局配置（~/.claude/settings.json）：

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

项目级配置（.claude/settings.json，只在当前项目有效）：

{
  "mcpServers": {
    "hermes": {
      "command": "/path/to/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

如果 hermes 不在 PATH 里，写绝对路径（virtualenv 里的 hermes 可执行文件路径）。

第三步：重启 Claude Code

配置后重启，Claude Code 会自动发现并连接 Hermes MCP Server。

在 Claude Code 里使用

连接成功后，在 Claude Code 里可以直接描述任务，它会调用 Hermes 工具：

例子 1：读取 Telegram 讨论

"读取 Telegram 频道 @my_tech_channel 最近 30 条消息，总结主要讨论的技术问题"

Claude Code 会调用 channels_list → messages_read → 分析内容。

例子 2：跨平台消息汇总

"把今天 Discord 服务器 general 频道和 Slack 的 #dev 频道的消息都拉过来，
整理成一份今日工作进展总结"

例子 3：审批管理

"查看 Hermes 里有没有待审批的操作，如果有，描述一下再问我是否批准"

事件实时监听

events_wait 工具支持阻塞等待新消息（最多指定秒数），可以实现实时响应：

# 这是 Claude Code 内部的工具调用逻辑
events_wait(max_wait=30)  # 等最多 30 秒，有新消息立即返回

轮询间隔：MCP Server 内部以 200ms 为周期轮询 SQLite，events_wait 收到事件后立即推送给 MCP 客户端，最大延迟约 200ms。

架构说明

消息平台（Telegram / Discord）
       ↓ 实时接收
Hermes Gateway（写入 SQLite）
       ↓ 本地读取
Hermes MCP Server（stdio）
       ↓ MCP 协议
Claude Code / Cursor / 其他 MCP 客户端

MCP Server 和 Gateway 可以在同一台机器上运行，也可以分开（通过 SSH 端口转发或网络挂载 SQLite 文件）。

FAQ

Q: 不用 Gateway，直接跑 MCP Server 会怎样？

工具可以调用，但 conversations_list 和 messages_read 返回空（没有数据）。messages_send 也不会真正发出去（没有 Gateway 连接平台）。MCP Server 只是数据层，数据来源是 Gateway。

Q: MCP Server 和 Hermes CLI 能同时运行吗？

可以，两者读取同一个 SQLite 文件，SQLite 支持多进程并发读（只有写入时短暂锁定）。实测没有冲突问题。

Q: 消息数据有隐私风险吗？

Hermes MCP Server 以 stdio 方式运行，只有启动它的进程（Claude Code）可以访问，不绑定网络端口，不对外暴露。消息数据存在本地 SQLite 文件，权限由本机文件系统控制。

Q: Claude Code Desktop App 也支持 MCP 配置吗？

支持，配置文件位置：macOS 是 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 是 %APPDATA%\Claude\claude_desktop_config.json，格式和上面一样。