Skip to main content
Glama
matthewmcneill

hermes-mcp-lite

by matthewmcneill
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

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").

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
session_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it delivers: it discloses the remote agent loop, 30-second-to-5-minute latency, streamed progress updates, persistent memory, and session-based context retention. This goes well beyond a generic 'delegate a task' statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then uses a scannable bullet list of usage domains, then documents parameters. Every sentence adds useful information, and there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description covers what an agent needs: what to pass, how to maintain context, expected timing, and what Hermes can do. Nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only titles and types with 0% description coverage, but the tool description fully compensates: it explains that prompt is the task instruction, advises specificity, and clarifies that session_id is optional and should be reused across related calls to maintain context, complete with an example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Delegate a task or question to the remote Hermes Agent.' It then lists concrete capability domains, making it unmistakable what the tool does and distinguishing it from the health-check sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this tool whenever you need Hermes to:' followed by a concrete list gives clear context for when to invoke it. It does not explicitly name the sibling hermes_health as an alternative or state when not to use this tool, so it stops short of full exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_healthA

Check if the remote Hermes Agent is reachable and healthy.

Returns the gateway health status including version information.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries full responsibility. It discloses that the tool performs a network reachability check and returns gateway health status and version information. For a zero-parameter health probe, this is sufficient behavioral context, though it omits auth or rate-limit caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The primary action is front-loaded, and the second sentence adds concrete value about return contents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple, parameterless health-check tool. The description covers what it does and what it returns, an output schema exists, and there are no hidden parameters or complex behaviors. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description cannot add parameter-level meaning. The input schema is empty, making this a healthy baseline without any param documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and a clear resource ('remote Hermes Agent') with a health-focused purpose. It also states the return content, making it distinct from sibling ask_hermes without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: call this when you need to verify reachability or health of the Hermes Agent. However, there is no explicit guidance about when not to use it or comparison to ask_hermes, so the routing relies on inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedask_hermes
    • First observedhermes_health
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
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.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/matthewmcneill/hermes-mcp-lite'

If you have feedback or need assistance with the MCP directory API, please join our Discord server