hermes-agent-mcp is a Model Context Protocol server that wraps the local hermes CLI over stdio. Point Claude Code, Cursor, Codex or any other MCP-capable agent at it and they can hand Hermes a task, read and change its config, manage cron jobs, restart the gateway and run hermes doctor — without a terminal and without ever seeing a token.

uvx hermes-agent-mcp

That is the whole install. No ports, no tunnel, no OAuth. It runs as a child process of your MCP client, on the same machine as Hermes, and nothing leaves the box.

_{mcp-name: io.github.woonyong-choi/hermes-agent-mcp}

Why this exists

Hermes is a great always-on agent, but everything about operating it happens in a terminal: hermes cron edit, hermes config set, hermes gateway restart. If the agent that wants to do those things has no terminal — a desktop app, a coding assistant sandboxed away from your shell — it is stuck asking a human to type for it.

There is already a good project called hermes-mcp by mlennie. It solves a different problem: reaching Hermes remotely, over HTTP through a cloudflared tunnel with OAuth, so a hosted client can delegate tasks. If that is what you need, use it.

This project was written by someone who did not want that. Opening a Hermes gateway to the internet means an agent with a shell is one leaked token away from anyone. hermes-agent-mcp stays local on purpose:

it never listens on a port — MCP over stdio only
it never handles credentials — it calls the CLI, which already has them
it exposes the operations surface (cron, config, gateway, doctor, skills), not just "send a prompt"

	hermes-agent-mcp (this)	hermes-mcp (mlennie)
Transport	stdio, local process	HTTP, tunnel + OAuth
Reachable from	MCP clients on the same machine	Anywhere
Surface	16 tools: ask + cron, config, gateway, doctor, skills, sessions	4 tools: ask, check, cancel, reset
Typed `config.yaml` writes	Yes	—
Network exposure	None	By design

Tools

Tool	What it does
`hermes_status`	Server config, whether the CLI answers, which tools are enabled
`hermes_ask`	Hand the agent a task and get its reply (one non-interactive turn)
`doctor`	`hermes doctor` health report
`gateway_status` / `gateway_restart`	Messaging gateway state and restart
`cron_list` / `cron_create` / `cron_edit` / `cron_run` / `cron_runs`	Scheduled jobs, including per-job model and reasoning effort
`config_get` / `config_set`	Typed reads and writes against `config.yaml`
`skills_list`	Installed skills
`sessions_list`	Recent sessions
`model_info`	Default model, provider and Nous Portal status
`shell`	Run a shell command on the host — off by default

`config_set` fixes a real trap

hermes config set platforms.telegram.reply_to_mode off stores the YAML boolean False, not the string "off". Several Hermes options compare against the string, so the setting silently does nothing. config_set takes an explicit value_type (str, int, float, bool, null, json), writes a .bak before touching the file, and returns the resulting section so you can see what landed.

Setup

Claude Code

claude mcp add hermes -- uvx hermes-agent-mcp

Cursor / Windsurf / Claude Desktop

{
  "mcpServers": {
    "hermes": {
      "command": "uvx",
      "args": ["hermes-agent-mcp"]
    }
  }
}

Hermes itself

Hermes can drive its own install — useful for a supervisor profile that manages other profiles. Add to ~/.hermes/config.yaml:

mcp_servers:
  hermes:
    command: uvx
    args: ["hermes-agent-mcp"]

From a clone

git clone https://github.com/woonyong-choi/hermes-agent-mcp
cd hermes-agent-mcp
uv tool install -e .

Configuration

Everything is an environment variable, so the same server works on macOS, Linux, WSL and inside a container that mounts someone else's ~/.hermes.

Variable	Default	Meaning
`HERMES_HOME`	`~/.hermes`	Hermes data directory
`HERMES_MCP_BIN`	`hermes` on `PATH`	Path to the CLI
`HERMES_MCP_ALLOW_WRITE`	`1`	Allow tools that change state (cron edit, config set, restart). Set `0` for read-only
`HERMES_MCP_ALLOW_SHELL`	`0`	Enable the `shell` tool
`HERMES_MCP_TIMEOUT`	`120`	Seconds for ordinary CLI calls
`HERMES_MCP_ASK_TIMEOUT`	`900`	Seconds for `hermes_ask`
`HERMES_MCP_MAX_OUTPUT`	`40000`	Characters returned per call before truncation

Security model

This server gives a language model the ability to operate an agent that has a terminal. The design assumes the model is talking to untrusted content and keeps the blast radius small:

Argument lists, never a shell. Every CLI call is subprocess.run([...]) with shell=False. Prompt text cannot become shell syntax.
Subcommand allowlist. Only config, cron, doctor, gateway, model, portal, profile, sessions, skills, tools and --version are reachable. hermes auth and anything that handles credentials is not, on purpose.
Redaction on every return. Telegram bot tokens, Anthropic/OpenAI/GitHub/Slack/AWS keys and JWTs are replaced with [redacted] before output reaches the model. .env is never read.
Read-only mode. HERMES_MCP_ALLOW_WRITE=0 blocks every state-changing verb.
Shell is opt-in. shell refuses to run until you set HERMES_MCP_ALLOW_SHELL=1, and you should only do that on a machine you control, for an agent you trust.

See SECURITY.md for reporting.

Releasing

Tag a version and CI publishes to PyPI via Trusted Publishing and attaches the wheel to a GitHub release:

git tag v0.1.0 && git push --tags

server.json at the repo root is the manifest for the MCP Registry; publish it with mcp-publisher publish after the PyPI release exists.

Development

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
ruff check .

Tests do not need a Hermes install; the runner is exercised against a missing binary and the config writer against a temp directory.

Compatibility

Built against Hermes Agent 0.21.x. The CLI is moving fast — if a subcommand's flags change, the tool returns the CLI's own error text rather than guessing. Issues and PRs that track upstream changes are welcome.