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

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

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