hermes-mcp

An MCP server for controlling a Hermes agent deployment over its HTTP API — from Claude Code, Claude Desktop, or any other MCP client.

It exposes the four things you actually do to a running agent: check on it, read its logs, give it work, and deploy or reconfigure it.

Status

The tool surface, transport, auth, and error handling are complete and tested. The endpoint paths are conventional defaults and have not been verified against a live Hermes deployment. You should not have to fix them by hand — run hermes-mcp doctor and it will work out the real ones and print the overrides to paste. See Pointing it at your deployment.

Install

Requires Python 3.10+ and uv.

git clone git@github.com:Stratfiy/hermes-mcp.git
cd hermes-mcp
uv sync

Configure

Only HERMES_BASE_URL is required.

Variable	Default	What it does
HERMES_BASE_URL	—	Required. Root URL of the deployment, e.g. https://hermes.example.com.
HERMES_API_KEY	—	Credential. Setting it alone turns on bearer auth.
HERMES_AUTH_STYLE	bearer when a key is set, else none	bearer, header, query, or none.
HERMES_API_KEY_HEADER	X-API-Key	Header (or query parameter) name when style is header/query.
HERMES_EXTRA_HEADERS	—	Static headers, Name: value per line. Useful for Cloudflare Access.
HERMES_TIMEOUT	30	Per-request timeout in seconds.
HERMES_VERIFY_TLS	true	Set false only for a self-signed staging host.
HERMES_READ_ONLY	false	Blocks every tool that changes the deployment.
HERMES_MAX_RESPONSE_CHARS	20000	Truncation ceiling, so a log dump can't swamp the context window.
HERMES_MCP_TRANSPORT	stdio	stdio, http, or sse.
HERMES_ROUTES_FILE	—	JSON file of route overrides.
HERMES_ROUTE_<NAME>	—	Override one route, e.g. HERMES_ROUTE_STATUS="GET /v1/state".

Pointing it at your deployment

Set the URL and credential, then let it work the rest out:

export HERMES_BASE_URL=https://hermes.example.com
export HERMES_API_KEY=your-token

uv run hermes-mcp doctor

doctor checks the host is reachable, checks your credentials are accepted, reads the deployment's OpenAPI schema, and compares every route it intends to call against what the deployment actually publishes. Output looks like:

Route check
-----------
[  ok  ] Matched against the deployment's OpenAPI schema.
[ warn ] not found: deploy, metrics, start, stop

Add these to your MCP server config:

  HERMES_ROUTE_STATUS="GET /api/v1/state"
  HERMES_ROUTE_TASK_CREATE="POST /api/v1/jobs"
  HERMES_ROUTE_TASK_GET="GET /api/v1/jobs/{task_id}"
  ...

Paste those in and every tool works against your paths. The same thing is available as the detect_routes tool once the server is registered, and describe_api reports it as part of a wider picture.

If the deployment publishes no schema, detect_routes falls back to probing candidate paths — using GET only. Discovering POST /stop by calling it would mean stopping your agent to learn that stopping it works, so mutating routes are never probed and must be set by hand.

Register with Claude Code

User scope, so it is available in every project:

claude mcp add --scope user hermes \
  --env HERMES_BASE_URL=https://hermes.example.com \
  --env HERMES_API_KEY=your-token \
  -- uv run --directory /absolute/path/to/hermes-mcp hermes-mcp

claude mcp list   # verify

To start read-only while you confirm the routes are right, add --env HERMES_READ_ONLY=1.

Tools

Lifecycle — health, status, start, stop, restart

Diagnostics — logs (filter by lines, level, since, search), metrics, describe_api, detect_routes

Work — send_task, get_task, list_tasks, cancel_task

Deploy and config — deploy, get_config, set_config

Escape hatch — request, for any endpoint the named tools don't model

stop, restart, cancel_task, deploy, and set_config are annotated destructive, so clients that surface that hint will ask before running them.

The route table

Prefer hermes-mcp doctor over editing this by hand. The defaults assume conventional REST paths:

GET  /health          GET  /logs         POST /tasks
GET  /status          GET  /metrics      GET  /tasks
POST /start           POST /deploy       GET  /tasks/{task_id}
POST /stop            GET  /config       POST /tasks/{task_id}/cancel
POST /restart         PATCH /config      GET  /openapi.json

When your deployment disagrees, override the route rather than editing code. One at a time:

export HERMES_ROUTE_TASK_CREATE="POST /agent/jobs"
export HERMES_ROUTE_STATUS="GET /v1/state"

Or all at once, with HERMES_ROUTES_FILE=routes.json:

{
  "status": "GET /v1/state",
  "logs": "GET /v1/logs",
  "task_create": "POST /agent/jobs",
  "task_get": "GET /agent/jobs/{task_id}"
}

A 404 from a tool says so explicitly and points back here.

Development

uv run pytest          # tests
uv run ruff check .    # lint
uv run ruff format .   # format

No test touches the network — HTTP is mocked with respx. CI runs the same three commands on Python 3.10 and 3.12.

CLI

hermes-mcp          # run the MCP server over stdio (what a client invokes)
hermes-mcp doctor   # check the deployment and print what it found