MCP 服务器

Hermes MCP Server

Enables AI clients to communicate with Hermes messaging middleware in real-time using MCP protocol, supporting conversations, messages, attachments, and permissions management.

README

Hermes MCP Server

基于 MCP（Model Context Protocol）的轻量级服务端程序，实现 AI 客户端与 Hermes 消息中间件之间的双向实时通信。

架构

┌─────────────────┐   Streamable HTTP    ┌──────────────────┐
│  MCP Client     │ ←─────────────────→ │  MCP Server      │
│  (Claude/AI)    │  POST /mcp (请求)     │  (Node.js:9120)  │
│                 │  GET  /mcp (SSE推送)  └────────┬─────────┘
└─────────────────┘  DELETE /mcp (终止)            │
                                          ┌─────────┼─────────┐
                                          │         │         │
                                          ▼         ▼         ▼
                                   ┌────────┐ ┌────────┐ ┌──────┐
                                   │Hermes  │ │SQLite  │ │缓存  │
                                   │HTTP API│ │state.db│ │(内存)│
                                   │:9119   │ │轮询    │ │      │
                                   └────────┘ └────────┘ └──────┘

MCP 客户端 → MCP Server：公网 9120 端口，Bearer API Key 认证
MCP Server → Hermes：仅内网 127.0.0.1:9119（不走公网）
事件推送：200ms 轮询 Hermes 的 SQLite state.db，变化时通过 SSE 推送

MCP 工具（10 个）

工具	功能
`conversations_list`	列出所有活跃会话（支持平台/关键词过滤）
`conversation_get`	获取会话详情
`messages_read`	读取消息历史
`attachments_fetch`	获取消息附件
`events_poll`	轮询新事件
`events_wait`	长轮询等待事件
`messages_send`	发送消息到平台
`channels_list`	列出可用频道
`permissions_list_open`	列出待审批请求
`permissions_respond`	响应审批

资源与提示词

资源：

hermes://status — Hermes 运行状态
hermes://channels — 已连接频道列表
hermes://sessions — 活跃会话列表

提示词：

summarize-conversations — 总结所有会话状态
check-health — Hermes 健康检查

部署

1. 环境要求

Node.js 20+
Hermes Agent 已安装并运行
端口 9120 可用

2. 安装

git clone https://github.com/Swcmb/hermes-mcp-server.git
cd hermes-mcp-server
npm install

3. 配置

cp .env.example .env
# 编辑 .env 填写实际值

关键配置项：

变量	说明	默认值
`MCP_PORT`	监听端口	9120
`MCP_API_KEY`	API Key（客户端认证用）	必填
`HERMES_API_URL`	Hermes API 地址	http://127.0.0.1:9119
`HERMES_GATEWAY_TOKEN`	Hermes Gateway Token	从 Hermes .env 读取
`HERMES_STATE_DB`	state.db 路径	/home/admin/.hermes/state.db
`MCP_MAX_SESSIONS`	最大并发会话	5

4. 启动

# 前台运行
npm start

# 或用 systemd（推荐生产环境）
sudo cp hermes-mcp-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hermes-mcp-server

5. 开放端口

在阿里云安全组中开放 TCP 9120 端口。

客户端配置

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "hermes": {
      "url": "http://YOUR_SERVER_IP:9120/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

其他 MCP 客户端

MCP 端点：http://YOUR_SERVER_IP:9120/mcp 认证头：Authorization: Bearer YOUR_API_KEY

测试

npm test

低资源优化

--max-old-space-size=256：限制 Node.js 堆内存 256MB
nice -n 19 + ionice -c 3：最低 CPU/IO 优先级
200ms 轮询 + mtime 短路：state.db 无变化时零开销
最大 5 个并发 SSE 会话
进程内缓存（60s TTL）减少重复请求

恢复

如果服务异常，检查：

# 服务状态
systemctl status hermes-mcp-server

# 日志
journalctl -u hermes-mcp-server -f

# 手动测试
curl -H "Authorization: Bearer YOUR_KEY" http://127.0.0.1:9120/mcp -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'