Hermes Bridge

Give Odin (or any MCP-compatible agent) a way to hand off tasks it can't do itself to a local Hermes Agent install — full terminal, file, browser, and coding tool access — and get a real answer back. Also supports scheduling recurring jobs (morning routines, daily reports) that Hermes runs on its own.

No webhooks, no servers, no Telegram relay for tasks. Just one Python file that Odin talks to directly on your own machine.

Fastest setup: let Hermes install itself

If you already have Hermes running and talk to it on Telegram, just message it:

install this: https://github.com/182moon/odin-hermes-bridge

Hermes will download the bridge, install its one dependency, detect its own install paths, and hand you back a ready-to-paste MCP config with your actual Telegram chat ID already filled in — no placeholders to edit. You just paste that block into Odin's MCP Servers → + Add panel. That's the only manual step left (Hermes can't click Odin's UI for you).

Prefer to do it yourself in a terminal instead of asking Hermes? Run:

curl -fsSL https://raw.githubusercontent.com/182moon/odin-hermes-bridge/main/install.sh | bash -s -- YOUR_TELEGRAM_CHAT_ID

(Omit the chat ID argument if you don't know it yet — the printed config will have a placeholder you can fill in by hand.)

The rest of this README covers the same setup done fully manually, plus how everything works under the hood.

What you get

Once set up, Odin gains four new tools:

Tool	What it does
run_hermes_task	Hand off a one-off task Odin can't do itself — Hermes runs it now and returns the result
schedule_hermes_task	Set up a RECURRING job (a morning routine, daily report, etc.) that Hermes runs on its own schedule, independent of Odin
list_scheduled_tasks	See what's currently scheduled
remove_scheduled_task	Cancel a scheduled job

run_hermes_task runs a full agent loop for a single task and returns the answer — use it for anything "do this now." schedule_hermes_task sets up a recurring job inside the user's own Hermes install using Hermes's built-in cron scheduler — use it for "do this every morning / every day / every Monday," etc. Scheduled jobs keep running even when Odin isn't open, as long as Hermes's own gateway/scheduler process is running on the user's machine (check with hermes cron status).

Important — where scheduled results go: Odin only creates the job; it has no way to receive results back later, since the job runs completely independently. schedule_hermes_task delivers results to a Telegram chat (the chat ID you already use with Hermes), not back into Odin. If you don't pass a telegram_chat_id (or set HERMES_TELEGRAM_CHAT_ID as a default — see Configuration knobs below), the job is created with deliver=local and its output only shows up in list_scheduled_tasks / hermes cron list — nobody gets notified. For an actual "morning briefing that lands on your phone," you need Hermes's Telegram gateway already connected (hermes gateway setup) and pass that chat's ID.

Requirements

• macOS, Linux, or WSL (same as Hermes itself)
• Python 3.9+
• Hermes Agent installed and configured with a working model (you'll use your own OpenRouter/ Anthropic/etc. key, same as Odin)

Setup (5 minutes)

1. Install Hermes, if you haven't already

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup

Confirm it works:

hermes chat -q "say hello"

2. Download this bridge folder

Save hermes_task_server.py and requirements.txt from this folder somewhere on your machine, e.g. ~/hermes-mcp-bridge/.

3. Install the one dependency

pip3 install -r ~/hermes-mcp-bridge/requirements.txt

(This installs the mcp Python package — the bridge script needs it to speak the MCP protocol. It's separate from Hermes itself.)

4. Find your hermes path

which hermes

Copy that path — you'll need it in the next step if hermes isn't already on Odin's PATH.

5. Add Hermes as an MCP server in Odin

Open Odin → MCP Servers → + Add → paste config, editing the paths to match your machine:

{
  "mcpServers": {
    "hermes": {
      "command": "python3",
      "args": ["/Users/yourname/hermes-mcp-bridge/hermes_task_server.py"],
      "env": {
        "HERMES_BIN": "/Users/yourname/.local/bin/hermes"
      }
    }
  }
}

Save. Odin should now show run_hermes_task as an available tool.

6. Test it

In Odin, ask it something you know it can't do on its own — e.g. "use Hermes to list the files in my Downloads folder" — and confirm it calls the tool and comes back with a real answer.

Then test scheduling — ask Odin something like "set up a Hermes job that runs every morning at 7am and gives me a weather + calendar briefing." Confirm it shows up with hermes cron list in a terminal, or ask Odin to list your scheduled tasks.

7. Keep the scheduler running

Recurring jobs created with schedule_hermes_task only fire while Hermes's scheduler is actually running in the background — not just when Odin happens to be open. Check status with:

hermes cron status

If it's not running, either start it in the foreground for testing:

hermes gateway run

(stays alive only while that terminal window is open — good for a quick test, not for production)

or install it as a real background service that survives reboots and terminal closures:

hermes gateway install
hermes gateway start
hermes gateway status   # confirm it's running

How it works

One-off tasks (run_hermes_task):

1. Odin calls run_hermes_task(task="...")
2. The bridge script runs hermes chat -q "<task>" as a subprocess on your machine
3. Hermes runs its full agent loop (its own tools, memory, skills — all of it) until the task is done
4. The final text answer is returned to Odin as the tool result

Recurring tasks (schedule_hermes_task):

1. Odin calls schedule_hermes_task(schedule="every day at 7am", task="...")
2. The bridge runs hermes cron create under the hood, registering a real job in the user's own Hermes install
3. Hermes's own scheduler fires the job on schedule — with or without Odin open — as long as the Hermes gateway/scheduler is running
4. list_scheduled_tasks / remove_scheduled_task wrap hermes cron list / hermes cron remove so Odin can manage jobs it created

Every call is independent — pass everything the calling agent knows about the task into the task text, since Hermes can't see Odin's conversation history or previous scheduled runs.

Configuration knobs

Env var	Purpose	Default
HERMES_BIN	Full path to the hermes executable	first match on PATH
HERMES_TASK_TIMEOUT	Max seconds to wait for a task	280
HERMES_TELEGRAM_CHAT_ID	Default Telegram chat ID for schedule_hermes_task results, so Odin doesn't need to ask for it every time	none — must be passed per call if unset

Find your Telegram chat ID by messaging your Hermes bot once, then checking hermes gateway status or your Hermes logs for the chat ID, or by asking Hermes itself "what's this chat's ID" in a Telegram conversation with it.

Set these in the "env" block of the MCP config shown above.

Troubleshooting

"No module named mcp" Run pip3 install mcp using the exact python3 your MCP config's "command" points to. If you have multiple Python installs, use the full path in both the install command and the config, e.g. /usr/bin/python3 -m pip install mcp.

"could not find the 'hermes' executable" Set HERMES_BIN in the MCP config's "env" block to the output of which hermes.

Tool call times out on long tasks Raise HERMES_TASK_TIMEOUT in the "env" block (seconds), or ask Odin to pass a higher timeout_seconds per call.

Odin doesn't see the tool after adding the server Restart Odin, or check its MCP server list for a connection error — usually a wrong path in "args" or "env".

Security note

This bridge runs Hermes with whatever tool access and permissions your Hermes install already has configured (terminal commands, file access, etc.). Anything Odin delegates through this tool runs with those same permissions on your machine. Only connect this to agents you trust.