hermes-cowork-bridge

An MCP (Model Context Protocol) stdio server that bridges Claude Cowork / Claude Desktop to a locally running Hermes Agent instance, plus a full setup guide for Hermes itself and pairing the bridge with filesystem/shell access.

It exposes three tools:

• hermes_delegate — send a task to Hermes for autonomous execution (terminal, file ops, web search, memory, skills, browser automation). Returns a run_id.

• hermes_check_run — poll a delegated task's status/result by run_id.

• hermes_health — check that Hermes is alive and reachable, and inspect its current status.

Why this exists

Claude Desktop's built-in "Add custom connector" UI has a known bug where servers with no OAuth flow fail to register ("Couldn't register with sign-in service"). This bridge sidesteps that entirely by registering as a stdio MCP server directly in claude_desktop_config.json, rather than going through the remote-connector OAuth discovery path.

Related MCP server: mcp-comfyui

Requirements

• Python 3.10+

• WSL2 with a Linux distro (Ubuntu recommended) if running on Windows

• Node.js installed on the Windows side (for the filesystem/shell additions below) — verify with node --version in PowerShell

• Claude Desktop

Part 0 — Installing and configuring Hermes Agent itself

If Hermes isn't installed yet, do this first. If it's already running, skip to Part 1, but read the config notes below — several of them fix real problems that surface once Hermes is under real use.

Install

pip install hermes-agent
# or follow the current install instructions at
# github.com/NousResearch/hermes-agent

Pick a model and provider

Hermes needs an LLM behind it. Run the interactive picker:

hermes model

Select a provider (OpenRouter is a solid default — wide model selection, one API key covers many models) and a specific model. Note the exact model ID shown — model catalogs change over time, and a model that existed at install time can be delisted later, causing silent 404s on every task. If that happens, rerun hermes model and pick a currently-live model from the actual list shown, don't reuse an old ID from memory or documentation.

Config file locations

• ~/.hermes/config.yaml — main config (model, provider, approvals, context limits)

• ~/.hermes/.env — secrets and server settings (API keys, API_SERVER_ENABLED, API_SERVER_KEY)

Settings worth checking/changing for a personal, single-user setup

Open ~/.hermes/config.yaml and check these:

Context file limit — if you have a large AGENTS.md or similar context file, the default character limit can silently truncate it:

context_file_max_chars: 80000

(default is often much lower — raise it if your context file is large; check for a truncation warning in the gateway startup logs to confirm this was actually the problem before changing it)

Subagent auto-approval — if Hermes spawns subagents/tool calls that sit waiting for approval with nothing to approve them (common in fully unattended/API-driven use), set:

agent:
  subagent_auto_approve: true

Global approvals mode — if delegated tasks hang on waiting_for_approval indefinitely with no way to approve them (e.g. calling Hermes via its API server from another program, not the interactive CLI), set:

approvals:
  mode: off

This disables all safety/approval prompts. Appropriate for a trusted, single-user, personal setup — not appropriate for multi-user, production, or anything where you want a human-in-the-loop gate before actions execute.

Fallback provider — protect against a single provider's rate limits or outages taking down every task:

fallback_providers:
  - provider: <a different provider you have access to>
    model: <a specific model on that provider>

Enable the API server

This bridge talks to Hermes over its API server, not the interactive CLI. In ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=<generate one yourself, see below>

This key isn't issued by anyone — it's a shared secret you invent, used only to authenticate this bridge to your own local Hermes instance. Generate a random one with either:

python3 -c "import secrets; print(secrets.token_hex(16))"

or

openssl rand -hex 16

Whatever string you get, use it as API_SERVER_KEY here and as HERMES_API_KEY in the bridge's own .env (Part 1, step 3) — the two must match exactly, character for character. There's no registration, no external service, no "correct" value — it just has to be the same string in both places.

Start the gateway

hermes gateway

Leave this running. If you see a NotFoundError / 404 on startup or on the first real task, the configured model has likely been delisted — rerun hermes model and pick a currently-live one.

Health check before moving on

In a second terminal:

curl http://127.0.0.1:8642/health/detailed

Confirm you get a real JSON response back, not a connection error, before proceeding to the bridge setup.

Part 1 — The Hermes bridge itself

1. Clone this repo into your WSL2 home directory, e.g.:

   git clone <this-repo-url> ~/hermes-cowork-bridge
   cd ~/hermes-cowork-bridge

2. Create a virtual environment and install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Copy .env.example to .env and set the same key you set in ~/.hermes/.env's API_SERVER_KEY above:

   cp .env.example .env
   # edit .env — HERMES_API_KEY must exactly match API_SERVER_KEY from ~/.hermes/.env

4. Sanity check both files agree:

   grep API_SERVER_KEY ~/.hermes/.env
   grep HERMES_API_KEY ~/hermes-cowork-bridge/.env

   The values after the = must be identical.

Part 2 — Locating and editing claude_desktop_config.json

Claude Desktop's config file location depends on how it was installed:

MSIX-packaged (Microsoft Store) installs on Windows:

C:\Users\<your-windows-username>\AppData\Local\Packages\Claude_<package-id>\LocalCache\Roaming\Claude\claude_desktop_config.json

The <package-id> segment is unique per install. If you don't know it, find it with PowerShell:

Get-ChildItem "C:\Users\<your-windows-username>\AppData\Local\Packages" -Filter "*Claude*"

Standard (non-Store) installs:

%APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist yet, create it — an empty install has no mcpServers key until you add one.

Part 3 — Registering all three MCP servers

Use claude_desktop_config.example.json in this repo as your starting template. It defines three servers together, since they're commonly used as a set:

• hermes — this bridge, giving Cowork task-delegation access to Hermes

• filesystem — direct read/write access to your WSL2 filesystem

• shell — direct command execution

Replace every placeholder before use:

• YOUR_WSL_USERNAME → your actual WSL2 username (run whoami inside WSL to confirm)

• YOUR_WSL_DISTRO_NAME → your WSL distro name as registered with Windows (run wsl --list in PowerShell to see it — commonly Ubuntu)

• Adjust the repo path if you cloned this bridge somewhere other than your home directory

The filesystem and shell servers specifically

These two matter enough to call out in detail, because the naive setup fails in a specific, non-obvious way.

The problem: if you configure filesystem or shell to launch via wsl.exe and then run npx inside WSL, it frequently fails with:

env: 'node': No such file or directory

This happens because Claude Desktop launches wsl.exe with a minimal environment that doesn't inherit your normal WSL shell's PATH — so even though node and npx work fine when you open a WSL terminal yourself, they're unreachable when Desktop spawns the process.

The fix: run these two servers via Windows-native Node, not WSL's Node. Point npx.cmd (Windows) at the WSL filesystem using the \\wsl$ UNC path instead of a Linux path:

"filesystem": {
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "\\\\wsl$\\YOUR_WSL_DISTRO_NAME\\home\\YOUR_WSL_USERNAME"
  ]
}

Adjust C:\\Program Files\\nodejs\\npx.cmd if your Node install lives elsewhere — confirm the real path with where npx in PowerShell.

For shell access specifically: the package name @modelcontextprotocol/server-shell does not exist on npm (a common mistake to copy from outdated guides) and will fail with a 404. Use a real, published package instead — bash-mcp is a working option:

"shell": {
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": ["-y", "bash-mcp"]
}

Be aware this launches on the Windows host via cmd.exe, not inside WSL. If you need it to run Linux/bash commands inside your WSL distro specifically, prefix every command with wsl.exe -d YOUR_WSL_DISTRO_NAME --, e.g.:

wsl.exe -d YOUR_WSL_DISTRO_NAME -- ps aux | grep hermes

Full example config

See claude_desktop_config.example.json in this repo for the complete three-server block, ready to drop into your real config file once placeholders are replaced.

Part 4 — Apply and verify

1. Fully quit Claude Desktop — right-click its icon in the system tray and choose Exit/Quit. Closing the window alone is not enough; the process keeps running in the background and won't pick up config changes.

2. Reopen Claude Desktop.

3. In a Cowork session, verify each server individually:

   Check if Hermes is healthy and reachable.

   List the files in my home directory.

   Run: ps aux | grep hermes

If any of these fail, check the relevant MCP log — Claude Desktop writes one log file per server under the logs subfolder next to claude_desktop_config.json (e.g. mcp-server-hermes.log, mcp-server-filesystem.log, mcp-server-shell.log). The actual error text there is almost always more useful than guessing.

Architecture notes

• The Hermes bridge runs as a stdio MCP server — Claude Desktop launches it as a subprocess and communicates over stdin/stdout. It is not an HTTP server itself; the HTTP calls to Hermes's own API happen internally.

• Hermes's API endpoints used: POST /v1/runs (submit task), GET /v1/runs/{run_id} (poll status), GET /health/detailed (health check).

• The filesystem and shell servers are unrelated to Hermes specifically — they're general-purpose MCP servers commonly paired with this bridge so Cowork can inspect logs, verify file state, and run diagnostic commands without round-tripping everything through hermes_delegate.

Troubleshooting

Roughly in the order you're likely to hit them during initial setup, then ongoing issues below that.

Setup-time issues

env: 'node': No such file or directory You're running filesystem or shell via WSL's wsl.exe launch instead of Windows-native Node. Use C:\Program Files\nodejs\npx.cmd (or wherever where npx in PowerShell points) instead. See Part 3.

npm error 404 on @modelcontextprotocol/server-shell That package doesn't exist on npm. Use bash-mcp or another real, verified-published package instead.

Error accessing directory C:\home\... The filesystem server resolved a Linux-style path (/home/...) as a Windows path because it's running under Windows Node. Use the \\wsl$\<distro>\home\<user> UNC path form instead.

Config changes don't seem to take effect Claude Desktop caches its config in the running process. Fully quit via the system tray icon — closing the window is not the same as quitting the app.

Server shows as connected but every tool call errors Check that the API key in this bridge's .env (HERMES_API_KEY) exactly matches API_SERVER_KEY in ~/.hermes/.env. A mismatch here won't stop the stdio connection from establishing, but every actual call to Hermes's API will fail auth.

Ongoing / operational issues

404 on every model call inside Hermes, even though it worked before The configured model was delisted by its provider. Model catalogs on aggregator platforms (OpenRouter and similar) change over time — a model ID that worked at install time isn't guaranteed to stay live. Run hermes model and pick a currently-listed model rather than reusing an old ID from memory, a config file, or documentation.

Runs stuck on waiting_for_approval with no way to approve them This happens when Hermes is driven through its API (as this bridge does) rather than the interactive CLI — there's no human present to click approve. Set approvals.mode: off in ~/.hermes/config.yaml. This is appropriate for a trusted single-user setup; it is not appropriate if multiple people can trigger tasks or if you want a human gate before actions execute.

Tasks fail or hang with no useful error, and the process has been running a very long time Long-running gateway or bridge processes can go stale — accumulate memory bloat, hold dead connections, or otherwise degrade — especially across many hours of continuous uptime. If something that used to work suddenly doesn't, and you can't find an obvious cause, kill and restart clean before debugging further:

pkill -9 -f "hermes gateway"
pkill -9 -f hermes_mcp_server.py
hermes gateway

Then fully quit and reopen Claude Desktop too, so it spawns fresh connections rather than reusing anything stale.

AGENTS.md or other context file seems to be getting cut off / Hermes seems to be missing context it should have Check the gateway startup logs for a truncation warning. If present, raise context_file_max_chars in ~/.hermes/config.yaml to a value larger than your actual file size.

A delegated task reports success, but the thing it claims to have built/changed doesn't actually exist Don't trust a subprocess's or sub-agent's self-reported summary at face value — independently verify by checking the actual file, running the actual command, or reading the actual log, rather than accepting a narrated "done" as fact. This is a real failure mode with autonomous agents generally, not specific to Hermes.

Rate limits or provider outages taking down every task Configure fallback_providers in ~/.hermes/config.yaml so a single provider's rate limit or downtime doesn't stop all work. See Part 0.

License

MIT — do whatever you want with this.