How to Stop Hermes MCP Servers from Respawning on macOS (LaunchAgent KeepAlive Fix)

fixing_hermes_orphaned_mcps.sh

# Fixing Orphaned Hermes MCP Servers on macOS

## Symptoms

- Killing Hermes processes doesn't work.
- MCP servers immediately come back.
- Activity Monitor fills with Node, Python, and npm processes.
- PPID is often `1`.
- `mcp_stdio_watchdog.py` continually respawns servers.

## Root Cause

Hermes installs `launchd` LaunchAgents with:

- KeepAlive
- RunAtLoad

These automatically restart the Hermes gateway, which recreates every configured MCP server.

## Find the LaunchAgents

```bash
ls -la ~/Library/LaunchAgents | grep -i hermes
```

Mine contained:

```text
ai.hermes.gateway.plist
com.hermes.webui.plist
com.hermespilot.link.plist
```

## Stop the services

```bash
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.hermes.gateway.plist
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.hermes.webui.plist
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.hermespilot.link.plist
```

## Remove the LaunchAgents

```bash
rm ~/Library/LaunchAgents/ai.hermes.gateway.plist
rm ~/Library/LaunchAgents/com.hermes.webui.plist
rm ~/Library/LaunchAgents/com.hermespilot.link.plist
```

## Kill any remaining Hermes processes

```bash
pkill -f 'hermes_cli.main gateway run'
pkill -f 'hermeslink daemon'
pkill -f 'hermes-webui/server.py'
```

## Verify

```bash
ps -axo pid,ppid,etime,command | grep -E \
'hermes_cli.main (serve|gateway)|hermeslink daemon|hermes-webui/server.py' \
| grep -v grep
```

```bash
ls ~/Library/LaunchAgents | grep -i hermes
```

Both commands should return nothing.

## Notes

This does **not** uninstall Hermes.

It only removes the background LaunchAgents responsible for automatically restarting Hermes and every MCP server attached to it.

hermes-mcp-cleanup-guide.md

Stop Hermes MCP Servers from Respawning on macOS

Hermes can install macOS launchd LaunchAgents that automatically start its gateway, WebUI, and link daemon.

When those LaunchAgents use KeepAlive and RunAtLoad, killing the visible MCP processes does not solve the problem. The Hermes gateway simply restarts and launches every configured MCP server again.

This guide shows how to identify and remove those persistent background services.

Symptoms

You may be dealing with this issue if:

• MCP servers immediately return after being killed
• Activity Monitor fills with Node, Python, npm exec, or MCP processes
• Processes have a parent process ID of 1
• mcp_stdio_watchdog.py keeps recreating servers
• Hermes processes return after closing Terminal or restarting your Mac

Root Cause

The MCP servers themselves are not the root problem.

They are child processes launched by a Hermes gateway. That gateway may be managed by a macOS LaunchAgent configured with:

KeepAlive
RunAtLoad

As long as the LaunchAgent remains loaded, macOS will keep restarting the gateway.

Find Running Hermes Services

ps -axo pid,ppid,etime,command | grep -E \
'hermes_cli.main (serve|gateway)|hermeslink daemon|Hermes.app/Contents/MacOS/Hermes' \
| grep -v grep

To inspect MCP-related child processes:

ps -axo pid,ppid,etime,command | grep -Ei \
'hermes_cli|mcp_stdio_watchdog|npm exec.*mcp|node.*mcp' \
| grep -v grep

Find Hermes LaunchAgents

ls -la "$HOME/Library/LaunchAgents" | grep -i hermes

Common examples include:

ai.hermes.gateway.plist
ai.hermes.gateway-pinchy.plist
com.hermes.webui.plist
com.hermespilot.link.plist

Your filenames may be different.

Stop the LaunchAgents

Unload each LaunchAgent before deleting it:

launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/ai.hermes.gateway.plist" 2>/dev/null
launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/com.hermes.webui.plist" 2>/dev/null
launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/com.hermespilot.link.plist" 2>/dev/null

For a named profile such as pinchy:

launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/ai.hermes.gateway-pinchy.plist" 2>/dev/null

Remove the LaunchAgent Files

rm -f "$HOME/Library/LaunchAgents/ai.hermes.gateway.plist"
rm -f "$HOME/Library/LaunchAgents/com.hermes.webui.plist"
rm -f "$HOME/Library/LaunchAgents/com.hermespilot.link.plist"
rm -f "$HOME/Library/LaunchAgents/ai.hermes.gateway-pinchy.plist"

Only remove files that actually exist on your system.

Kill Remaining Hermes Processes

pkill -f 'hermes_cli.main gateway run' 2>/dev/null || true
pkill -f 'hermeslink daemon' 2>/dev/null || true
pkill -f 'hermes-webui/server.py' 2>/dev/null || true

Avoid broad commands such as:

pkill node
pkill python

Those can terminate unrelated applications and development tools.

Verify the Fix

Check that no Hermes services remain:

ps -axo pid,ppid,etime,command | grep -E \
'hermes_cli.main (serve|gateway)|hermeslink daemon|hermes-webui/server.py' \
| grep -v grep

Check that no Hermes LaunchAgents remain:

ls -la "$HOME/Library/LaunchAgents" | grep -i hermes

Both commands should return no output.

You can also verify a specific service:

launchctl print gui/$(id -u)/ai.hermes.gateway

A successful removal should produce a message similar to:

Could not find service "ai.hermes.gateway"

Important Notes

This does not uninstall Hermes.

It only removes the macOS LaunchAgents responsible for automatically starting and restarting Hermes background services.

You can still launch Hermes manually later.

A Hermes update or reinstall may recreate the LaunchAgents, so check ~/Library/LaunchAgents again if the problem returns.

Why Killing Individual MCP Servers Fails

The process tree usually looks like this:

macOS launchd
└── Hermes gateway
    └── mcp_stdio_watchdog.py
        └── npm, node, uvx, or Python MCP server

Killing the MCP server only removes the final child process.

The watchdog or gateway recreates it. The permanent fix is to unload the LaunchAgent that keeps the gateway alive.

Disclaimer

Review every command before running it.

LaunchAgent names can vary between installations, profiles, and Hermes versions. Do not delete unrelated .plist files from ~/Library/LaunchAgents.