MCP Health Monitor#

Automated health monitoring for MCP servers and AI services. Detects failures, auto-restarts services via launchctl, and sends Telegram alerts on incidents. Silent when everything is healthy.

Supported Check Types#

TypeMethodAuto-RestartHTTP Healthcurl endpoint checkYes (via launchctl)Processpgrep process detectionYes (via launchctl)Process-onlypgrep detectionNo (expects external spawn)

Quick Start#

1. Install the healthcheck script#

bash

# Copy the script to your preferred location
cp scripts/healthcheck.sh ~/.local/bin/mcp-healthcheck.sh
chmod +x ~/.local/bin/mcp-healthcheck.sh

2. Configure environment variables#

Create or update your .env file (path configurable via ENV_FILE):

bash

# Required for Telegram alerts (optional — script works without them)
TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_CHAT_ID=your-chat-id-here

3. Configure services to monitor#

Edit the SERVICES array in healthcheck.sh. Each entry follows this format:

text

name|check_type|target|launchctl_label

Fields:

• name — Display name for logs and alerts
• check_type — http (HTTP endpoint) or process (pgrep pattern)
• target — URL for http checks, or process grep pattern for process checks
• launchctl_label — macOS launchctl service label for auto-restart (use none to skip restart)

Default configuration:

bash

SERVICES=(
  "Claw-Empire|http|http://127.0.0.1:8790/api/health|com.claw-empire.server"
  "Hermes-Gateway|process|hermes_cli.main gateway|ai.hermes.gateway"
  "mem0-MCP|process|mem0_mcp/server.py|none"
  "Brave-Search-MCP|process|brave-search-mcp-server|none"
  "Context7-MCP|process|context7-mcp|none"
)

4. Set up automated scheduling (macOS LaunchAgent)#

Create ~/Library/LaunchAgents/com.mcp-health-monitor.plist:

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.mcp-health-monitor</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>~/.local/bin/mcp-healthcheck.sh</string>
  </array>
  <key>StartInterval</key>
  <integer>300</integer>
  <key>StandardOutPath</key>
  <string>~/.local/logs/mcp-healthcheck-stdout.log</string>
  <key>StandardErrorPath</key>
  <string>~/.local/logs/mcp-healthcheck-stderr.log</string>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

Load the agent:

bash

launchctl load ~/Library/LaunchAgents/com.mcp-health-monitor.plist

5. Linux alternative (systemd timer or cron)#

bash

# crontab -e
*/5 * * * * /path/to/mcp-healthcheck.sh

For systemd, replace launchctl stop/start calls in the script with systemctl restart.

Environment Variables#

VariableRequiredDescriptionENV_FILENoPath to .env file (default: $HOME/.env)LOG_FILENoPath to log file (default: $HOME/.local/logs/mcp-healthcheck.log)TELEGRAM_BOT_TOKENNoTelegram Bot API token for alertsTELEGRAM_CHAT_IDNoTelegram chat/group ID for alertsHTTP_TIMEOUTNoHTTP check timeout in seconds (default: 5)RESTART_DELAYNoSeconds to wait between stop and start (default: 3)

Log Format#

Structured log entries:

text

[2026-03-30 14:00:00] [Claw-Empire] [OK] healthy (HTTP 200)
[2026-03-30 14:00:00] [mem0-MCP] [FAIL] not running (process not found)
[2026-03-30 14:00:00] [SYSTEM] [ALERT] 1 failures detected — sending notification

Telegram Alert Format#

Alerts are only sent when failures are detected. No notification on all-healthy runs.

text

🚨 *MCP Health Check Alert*
2026-03-30 14:00:00

Failures detected (1):
* mem0-MCP (process not found)

Services with launchctl labels were auto-restarted.
Process-only services await external respawn.

Customization#

Adding a new service#

Append to the SERVICES array:

bash

SERVICES+=(
  "My-Custom-MCP|process|my-custom-mcp-server|com.my-custom.mcp"
)

HTTP check with custom port#

bash

SERVICES+=(
  "My-API|http|http://127.0.0.1:3000/health|com.my-api.server"
)

Disable auto-restart for a service#

Set the launchctl label to none:

bash

"My-Service|process|my-service-pattern|none"

Troubleshooting#

IssueSolutionTelegram alerts not sendingVerify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in your .env``launchctl restart failsCheck the service label matches your .plist file nameFalse positives on process checksAdjust the pgrep pattern to be more specificLog file growing too largeSet up logrotate or periodic cleanup via cron