Skip to main content
Glama

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: Leetcoder

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

Tool

Description

ask_hermes(prompt, session_id?)

Delegate any task to Hermes's full agent loop

hermes_health()

Check if the remote Hermes gateway is reachable

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

Variable

Required

Default

Description

HERMES_API_KEY

yes

—

API_SERVER_KEY from the Hermes instance

HERMES_API_URL

no

http://localhost:8642

Hermes gateway base URL

HERMES_MODEL

no

hermes-agent

Model identifier for chat completions

HERMES_TIMEOUT

no

300

Request timeout in seconds

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

hermes-mcp-lite

hermes-mcp

Transport

stdio (spawned by client)

Streamable HTTP (persistent server)

Auth

None needed (client spawns it)

OAuth 2.1 + PKCE

Tunnel

Not needed

Cloudflare / ngrok required

Setup

1 env var + restart client

OAuth credentials + tunnel + systemd

Best for

Same-machine or VPN access

Public internet access

License

MIT

Available Tools

2 tools
ask_hermesA

Delegate a task or question to the remote Hermes Agent.

Hermes runs a full agent loop with tool calling, so responses typically take 30 seconds to 5 minutes depending on complexity. Progress updates are streamed back while Hermes works.

Use this tool whenever you need Hermes to:

  • Control smart home devices via Home Assistant

  • Send or read WhatsApp messages

  • Interact with Google Workspace (Gmail, Calendar, Drive, Docs, Sheets)

  • Browse the web or scrape pages

  • Schedule cron jobs or recurring tasks

  • Access Hermes's persistent memory and skills

  • Perform any task that requires Hermes's own tool set

Args: prompt: The task instruction or question for Hermes. Be specific about what you want it to do. session_id: Optional session identifier. Pass the same value across related calls to let Hermes maintain conversational context (e.g. "draft an email" → "now send it").

Inputs: prompt (required), session_id. Returns: result

hermes_healthA

Check if the remote Hermes Agent is reachable and healthy.

Returns the gateway health status including version information.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    ask_hermes and hermes_health have completely distinct purposes: one delegates tasks to the remote agent, the other checks connectivity and health. There is no overlap or ambiguity between them.

    Naming Consistency3/5

    ask_hermes follows a verb_noun pattern, while hermes_health follows a noun_pattern. The 'hermes' prefix is present in both, but the word order and style are inconsistent, making naming conventions mixed.

    Tool Count3/5

    At 2 tools, the server is borderline thin per the calibration, but it also intentionally serves as a 'lite' proxy to a remote agent. The count is reasonable for the narrow scope, though it does not feel fully fleshed out.

    Completeness4/5

    For a server whose purpose is to delegate tasks to Hermes, ask_hermes covers the core capability, and hermes_health provides operational visibility. Some possible gaps exist (no cancellation or session listing), but these are minor for a lite wrapper.

    Related MCP Connectors

    Related MCP Servers