Skip to main content
Glama
hermes-mcp-remote

hermes-mcp-remote

by kevincolten

hermes-mcp-remote

Control a Hermes Agent instance from claude.ai, Claude mobile, or any other MCP client.

Hermes is primarily a CLI. This is a small bridge that spawns hermes ... and exposes it over MCP Streamable HTTP with bearer auth. It ships as a Docker image built on top of the official nousresearch/hermes-agent image, with the bridge added as an s6-supervised service next to the gateway and dashboard, so every call runs against the same /opt/data the agent uses.

claude.ai / Claude mobile
        │  HTTPS
        ▼
your gateway or tunnel          ← OAuth, TLS
        │  HTTP (Docker network)
        ▼
hermes-mcp-remote  (this)       ← bearer token, refusal list, background jobs
        │  spawn
        ▼
hermes CLI  →  /opt/data        ← same container as the gateway + dashboard

The official hermes mcp serve only exposes messaging (list conversations, send). This exposes the operator surface: ask the agent, sessions, logs, profiles, cron, kanban, skills, plugins, config, and a verbatim hermes_run for everything else.

Tools

Tool

Runs

hermes_ask

hermes [-p profile] [-m model] -z "<prompt>" one-shot agent turn, final text only

hermes_run

hermes <args...> verbatim, with an optional stdin

hermes_help

hermes [cmd] --help

hermes_jobs

list / get / cancel background jobs

hermes_status, hermes_logs, hermes_sessions, hermes_gateway, hermes_profile, hermes_cron, hermes_kanban, hermes_project, hermes_config, hermes_model, hermes_fallback, hermes_auth, hermes_skills, hermes_bundles, hermes_plugins, hermes_mcp, hermes_tools, hermes_send, hermes_memory, hermes_insights, hermes_monitoring, hermes_approvals, hermes_hooks, hermes_webhook, hermes_peer, hermes_pairing, hermes_checkpoints, hermes_worktree, hermes_backup, hermes_doctor, hermes_dump, hermes_security, hermes_curator, hermes_journey, hermes_skin, hermes_pets, hermes_dashboard

hermes <name> <args...> with a per-command cheat sheet in the description

Every tool accepts profile, timeout_sec, and background. With background: true the call returns a job_id right away; poll it with hermes_jobs. Use that for agent turns and anything else that can outlast a client's tool-call limit (claude.ai's is about two minutes).

Results are JSON: status, exit_code, stdout, stderr, command. ANSI escapes are stripped.

What it refuses

Anything that needs a TTY, never returns, or would mutate the immutable image: setup, the chat REPL, --tui/--cli, gateway run, starting the dashboard, mcp serve, sessions browse, config edit, logs -f, console, desktop, acp, serve, update, uninstall. Set HERMES_MCP_ALLOW=update,... to unblock specific ones. Set HERMES_MCP_READ_ONLY=1 to allow only read-style commands.

Related MCP server: hermes-mcp

Deploy

The image is published at ghcr.io/kevincolten/hermes-mcp-remote:latest and rebuilds weekly on top of the latest upstream image. Swap it in for nousresearch/hermes-agent and add one variable:

services:
  hermes:
    image: ghcr.io/kevincolten/hermes-mcp-remote:latest
    command: gateway run
    shm_size: 1gb
    volumes:
      - hermes_data:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=...
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=...
      - HERMES_DASHBOARD_BASIC_AUTH_SECRET=...
      - HERMES_MCP_TOKEN=...          # openssl rand -base64 32

See docker-compose.yml for the full Coolify example. The bridge listens on 0.0.0.0:8788 inside the container and is not published; reach it over the Docker network from whatever fronts it (http://hermes:8788/mcp). If HERMES_MCP_TOKEN is unset the service stays down and the rest of the container runs exactly like upstream.

Check it:

docker exec <container> curl -s localhost:8788/healthz
docker exec <container> s6-svstat /run/service/hermes-mcp

Exposing it to claude.ai

claude.ai connects from Anthropic's servers and only speaks OAuth to custom connectors, so this needs something in front of it: an MCP gateway that does OAuth and forwards with the bearer token, or a Cloudflare Tunnel plus an OAuth proxy. The bridge itself stays on the Docker network.

Run it outside Docker

Works anywhere the hermes CLI is installed:

git clone https://github.com/kevincolten/hermes-mcp-remote.git
cd hermes-mcp-remote
npm install
cp .env.example .env    # set HERMES_MCP_TOKEN
npm start

Set HERMES_BIN and HERMES_HOME if they differ from the defaults.

Configuration

Variable

Default

Purpose

HERMES_MCP_TOKEN

required

Bearer token, 24+ chars

PORT / HOST / MCP_PATH

8788 / 0.0.0.0 / /mcp

Listener

HERMES_BIN / HERMES_HOME

hermes / /opt/data

CLI location and working directory

HERMES_MCP_TIMEOUT_SEC

90

Default per-call timeout (hermes_ask defaults to 600)

HERMES_MCP_MAX_TIMEOUT_SEC

3600

Ceiling clients can request

HERMES_MCP_READ_ONLY

unset

1 allows only read-style commands

HERMES_MCP_ALLOW

unset

Comma-separated command names to unblock

HERMES_MCP_MAX_OUTPUT

200000

Bytes kept per stream

HERMES_MCP_JOB_TTL_MIN

120

How long finished jobs stay pollable

Security notes

  • The token grants whatever the hermes user can do in the container, including -z prompts with approvals bypassed. Treat it like a shell.

  • Keep the gateway's own approval hooks on and never run Hermes with --yolo.

  • The service runs as the unprivileged hermes user (UID 10000) via s6-setuidgid, same as the gateway and dashboard.

Test

npm test

Runs the bridge against a fake hermes binary and checks auth, tool listing, one-shot, profile routing, refusals, failure reporting, timeouts, and background jobs.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      MCP sidecar for Hermes Agent exposing operator tools (cron, skills, config, workspace) with tiered read-only/operator/owner modes and dry-run by default for safe local development.
      43
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      MCP server for controlling a Hermes agent deployment via its HTTP API, enabling health checks, log retrieval, task management, and deployment configuration from MCP clients.
      17
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables governed remote execution of Hermes Agent tasks over MCP with client authentication, RBAC, audit logging, and human-in-the-loop approvals.
      -