mcp-health-monitor（MCP health monitor 搜索）

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

Quick Start

1. Install the healthcheck script

# 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):

# 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:

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:

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 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:

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

5. Linux alternative (systemd timer or cron)

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

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

Environment Variables

Log Format

Structured log entries:

[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.

🚨 *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:

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

HTTP check with custom port

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:

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

Troubleshooting