Hermes MCP Server
Summary
The Hermes MCP Server is a functional interface that allows the Hermes Agent to act as a Model Context Protocol (MCP) provider. This enables external MCP-capable agents—such as Claude Code, Cursor, or Codex—to list conversations, read message history, and send messages across all messaging platforms (Telegram, Slack, Discord, WhatsApp) connected to the Sokrates stack.
Details
The Hermes MCP Server bridges the gap between local development tools and the communication channels managed by the Hermes gateway. By running the command hermes mcp serve, the agent starts a stdio-based MCP server that exposes Hermes’s messaging capabilities to any compliant MCP client.
Configuration and Usage
To integrate Hermes with an MCP client like Claude Desktop or Claude Code, the server must be defined in the client’s configuration file (e.g., ~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"hermes": {
"command": "hermes",
"args": ["mcp", "serve"]
}
}
}The server can also be run with the --verbose flag for debug logging on stderr.
Available Tools
The server exposes 10 primary tools that expose Hermes channel messaging capabilities, providing a standardized way for AI agents to interact with disparate messaging platforms:
| Tool | Description |
|---|---|
conversations_list | Lists active messaging conversations, with support for platform filtering or name searching. |
conversation_get | Retrieves detailed information about a specific conversation via its session key. |
messages_read | Fetches recent message history for a specific conversation. |
attachments_fetch | Extracts non-text media (images, etc.) from a specific message. |
events_poll | Non-blocking tool to check for new conversation events since a specific cursor position. |
events_wait | Blocking long-poll tool that waits for the next event (near-real-time). |
messages_send | Sends a message through a platform (e.g., telegram:123456). |
channels_list | Lists all available messaging targets across all connected platforms. |
permissions_list_open | Lists pending approval requests observed during the session. |
permissions_respond | Allows or denies a pending approval request. |
Architecture and Event System
The MCP server operates by reading conversation data directly from the Hermes session store, specifically ~/.hermes/sessions/sessions.json and the associated SQLite database. A background thread monitors these files for changes, using mtime-optimized polling at approximately 200ms intervals to minimize CPU overhead.
The event system utilizes a cursor-based approach. Clients can use events_poll(after_cursor=N) or events_wait to stay synchronized with incoming messages. Supported event types include message, approval_requested, and approval_resolved.
Operational Requirements:
- Read Operations: Listing conversations, reading history, and polling events can function even if the main Hermes gateway is offline, as the server reads directly from the persistent session store.
- Write Operations: Sending messages (
messages_send) requires the Hermes gateway service to be active, as it relies on the live platform adapters and their respective network connections.
Current Limitations
As of the current implementation, the Hermes MCP Server supports only the stdio transport protocol. It does not yet support HTTP transport or the claude/channel push notification protocol. Additionally, message sending is currently limited to text only; sending media or attachments through the MCP interface is not yet supported.