hermes-mcp
Controls a Hermes agent deployment over its HTTP API, providing tools for lifecycle management (health, status, start, stop, restart), diagnostics (logs, metrics, API description, route detection), task management (send, get, list, cancel), deployment and configuration (deploy, get/set config), and a raw request escape hatch.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hermes-mcp check the agent's health status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncConfigure
Only HERMES_BASE_URL is required.
Variable | Default | What it does |
| — | Required. Root URL of the deployment, e.g. |
| — | Credential. Setting it alone turns on bearer auth. |
|
|
|
|
| Header (or query parameter) name when style is |
| — | Static headers, |
|
| Per-request timeout in seconds. |
|
| Set false only for a self-signed staging host. |
|
| Blocks every tool that changes the deployment. |
|
| Truncation ceiling, so a log dump can't swamp the context window. |
|
|
|
| — | JSON file of route overrides. |
| — | Override one route, e.g. |
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 doctordoctor 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 # verifyTo 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.jsonWhen 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 . # formatNo 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 foundAvailable Tools
17 toolscancel_taskADestructive
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
deployADestructive
Deploy Hermes on the host — pull new code and bring it up.
Inputs: ref, restart_after. Returns: object
describe_apiARead-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_routesBRead-onlyIdempotent
Work out this deployment's real endpoints and emit the overrides for them.
Inputs: probe. Returns: object
get_configARead-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_taskARead-onlyIdempotent
Read one Hermes task: its state, result, and any error it recorded.
Inputs: task_id (required). Returns: object
healthARead-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_tasksARead-onlyIdempotent
List recent Hermes tasks, newest first.
Inputs: limit, state. Returns: object
logsARead-onlyIdempotent
Read recent Hermes logs.
Inputs: level, lines, since, search. Returns: object
metricsARead-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
restartADestructive
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_configCDestructive
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
statusARead-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
stopADestructive
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
Scored across 17 tools
Most tools target distinct resources and actions, but health/status and describe_api/detect_routes have overlapping purposes; descriptions generally mitigate confusion.
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.
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.
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
Related MCP Connectors
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Argentic MCP server: run and inspect long-running agents on Argentic.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server that allows Claude Desktop and other MCP clients to delegate tasks to a local Hermes Agent for automation and persistent operations.46 PyPI70Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA control-plane MCP server for launching and supervising hcom-managed agents, running as a single persistent HTTP server to coordinate multiple sessions.2MIT
- AlicenseCqualityDmaintenanceMCP 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.431MIT
- FlicenseAqualityDmaintenanceMCP server that integrates Conductor Cloud with Hermes Agent, enabling Hermes to create sandboxed coding workspaces, dispatch tasks to developer agents (Claude, Codex, Cursor, ACP), and monitor or retrieve session results via MCP tools.8-