# hermes-mcp-lite

Lightweight MCP bridge that connects AI agents (Claude Desktop, Google Antigravity, Cursor, Codex) to a running **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** instance via its OpenAI-compatible gateway API.

Unlike the full [`hermes-mcp`](https://github.com/mlennie/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
```

## 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

```bash
# 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:

```bash
grep API_SERVER_KEY ~/.hermes/.env
```

If Hermes runs in Docker:
```bash
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):

```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"
      }
    }
  }
}
```

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

```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](https://github.com/NousResearch/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](https://github.com/mlennie/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