Skip to main content
Glama

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.

Related MCP server: hcom-mcp

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

Available Tools

17 tools
cancel_taskA
Destructive

Cancel a running Hermes task.

Whatever the task had already done externally is not undone — this stops further work, it does not roll back.

Inputs: task_id (required). Returns: object

deployA
Destructive

Deploy Hermes on the host — pull new code and bring it up.

Inputs: ref, restart_after. Returns: object

describe_apiA
Read-onlyIdempotent

Show how this server is configured and which endpoints Hermes actually has.

Returns the active base URL, auth style, and route table, plus the deployment's own OpenAPI schema when it publishes one. Run this first against a new deployment: the built-in route paths are conventional defaults, and any that do not match can be corrected with HERMES_ROUTE_<NAME> or HERMES_ROUTES_FILE rather than a code change.

Inputs: no named parameters. Returns: object

detect_routesB
Read-onlyIdempotent

Work out this deployment's real endpoints and emit the overrides for them.

Inputs: probe. Returns: object

get_configA
Read-onlyIdempotent

Read the Hermes deployment's current configuration.

Values the deployment considers secret are usually returned masked. Do not assume anything here is safe to echo back into a shared channel.

Inputs: no named parameters. Returns: object

get_taskA
Read-onlyIdempotent

Read one Hermes task: its state, result, and any error it recorded.

Inputs: task_id (required). Returns: object

healthA
Read-onlyIdempotent

Check whether the Hermes deployment is reachable and healthy.

Use this first when something looks wrong — it separates "the agent is down" from "the agent is up but misbehaving".

Inputs: no named parameters. Returns: object

list_tasksA
Read-onlyIdempotent

List recent Hermes tasks, newest first.

Inputs: limit, state. Returns: object

logsA
Read-onlyIdempotent

Read recent Hermes logs.

Inputs: level, lines, since, search. Returns: object

metricsA
Read-onlyIdempotent

Read resource and throughput metrics from the Hermes deployment.

Inputs: no named parameters. Returns: object

requestA

Call any Hermes endpoint directly, for anything the named tools miss.

Inputs: path (required), method (required), body, query. Returns: object

restartA
Destructive

Restart the Hermes agent.

Use this after a deploy or a config change that needs a fresh process. Causes a brief outage; in-flight work may be dropped.

Inputs: no named parameters. Returns: object

send_taskB

Send the Hermes agent a task to work on.

Inputs: prompt (required), wait, metadata. Returns: object

set_configC
Destructive

Update Hermes configuration values.

Inputs: values (required), restart_after. Returns: object

startA

Start the Hermes agent.

Safe to call when the agent is already running — most deployments treat it as a no-op — but check status first if you are unsure.

Inputs: no named parameters. Returns: object

statusA
Read-onlyIdempotent

Read the Hermes agent's current run state.

Returns whatever the deployment reports: process state, uptime, version, queue depth. Prefer this over start when you only need to know if the agent is already running.

Inputs: no named parameters. Returns: object

stopA
Destructive

Stop the Hermes agent.

This takes the agent offline: in-flight work may be dropped and the agent will not accept new tasks until it is started again. Confirm with the user before calling this against a production deployment.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, but health/status and describe_api/detect_routes have overlapping purposes; descriptions generally mitigate confusion.

    Naming Consistency3/5

    Mix of single-word nouns (health, status, logs, metrics) and verb_noun forms (get_task, send_task, set_config); the pattern is readable but not consistently applied.

    Tool Count3/5

    At 17 tools, the set sits at the borderline upper end of typical scope; some redundancy (health/status, describe_api/detect_routes) adds bulk, but each tool has a clear role.

    Completeness4/5

    The surface covers lifecycle, monitoring, task management, configuration, and API introspection, with a request fallback for gaps; minor redundancy but no major missing operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A control-plane MCP server for launching and supervising hcom-managed agents, running as a single persistent HTTP server to coordinate multiple sessions.
      2
      MIT
    • 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