hermes-mcp-lite

Lightweight MCP bridge that connects AI agents (Claude Desktop, Google Antigravity, Cursor, Codex) to a running Hermes Agent instance via its OpenAI-compatible gateway API.

Unlike the full hermes-mcp which requires OAuth 2.1 and a Cloudflare tunnel, this bridge runs as a simple stdio MCP server — no tunnel, no OAuth, no public endpoint needed. Just point it at your Hermes gateway and go.

Architecture

MCP Client (Claude Desktop / Antigravity / Cursor)
    │ stdio (JSON-RPC)
    ▼
hermes-mcp-lite (this script)
    │ HTTP POST /v1/chat/completions (streaming SSE)
    │ Bearer auth via API_SERVER_KEY
    ▼
Hermes Agent Gateway (:8642)
    │ Full agent loop with tool calling
    ▼
Home Assistant · WhatsApp · Google Workspace · Web · Cron · Memory

Related MCP server: any-model-plugin

Features

• Streaming with progress — Uses SSE streaming from the Hermes API and emits MCP report_progress notifications so the calling agent sees Hermes is actively working (prevents timeouts on long tasks)

• Zero config server — Single Python file, two dependencies

• Session threading — Pass session_id across related calls for multi-turn context

• Graceful fallback — Falls back to non-streaming if the gateway returns 400

Tools Exposed

Quick Start

1. Install

# Option A: Run directly with uv (recommended — handles deps automatically)
uv run --directory /path/to/hermes-mcp-lite python server.py

# Option B: Install into a venv
cd hermes-mcp-lite
pip install httpx mcp

2. Get the API key

The API_SERVER_KEY is auto-generated by Hermes when the dashboard is enabled. Find it in ~/.hermes/.env on the machine running Hermes:

grep API_SERVER_KEY ~/.hermes/.env

If Hermes runs in Docker:

docker exec hermes grep API_SERVER_KEY /opt/data/.env

3. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hermes": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hermes-mcp-lite", "python", "server.py"],
      "env": {
        "HERMES_API_URL": "http://your-hermes-host:8642",
        "HERMES_API_KEY": "your-api-server-key"
      }
    }
  }
}

Google Antigravity (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "hermes": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hermes-mcp-lite", "python", "server.py"],
      "env": {
        "HERMES_API_URL": "http://your-hermes-host:8642",
        "HERMES_API_KEY": "your-api-server-key"
      }
    }
  }
}

4. Restart your MCP client

The ask_hermes and hermes_health tools will appear in the available tool list.

Try: "Use Hermes to check what Home Assistant devices are online"

Environment Variables

Prerequisites

• Python ≥ 3.11

• A running Hermes Agent instance with the gateway API enabled

• Network connectivity to the Hermes gateway (localhost, LAN, VPN, etc.)

How it differs from hermes-mcp

License

MIT