{
  "markdown": "# MCP Server Health Monitor\n\nnpm `mcp-server-health-monitor` package\n\nMCP-native health monitoring that speaks the protocol, not just HTTP. Instead of pinging a port, it calls `list_tools` on each server — the same handshake your agent uses — so a green status means the server is actually ready to serve MCP requests. All health history stays local in SQLite; no external monitoring service required.\n\n[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting)\n\n## Key features\n\n- **Auto-discovery**: Reads your existing MCP config files (Claude Desktop, Cursor, VS Code) with no extra setup.\n- **Non-intrusive probing**: Only calls `list_tools` on target servers — read-only, no side effects.\n- **Version drift detection**: Compares tool schemas across checks to detect when a server has been updated.\n- **Historical trends**: Stores latency history in SQLite; p50/p95 are computed on-demand from stored history to surface regressions before they become outages.\n- **HTML dashboard**: Generates a self-contained health dashboard with uptime sparklines per server.\n- **Background polling**: Runs as a daemon so health data is always fresh when you ask for it.\n\n## Why this over generic uptime monitors?\n\nGeneric uptime monitors (UptimeRobot, Pingdom, BetterStack) check whether a port is open or an HTTP endpoint returns 200. That's not enough for MCP servers — a server can be running but failing to negotiate the MCP protocol or returning a broken tool schema.\n\n|                        | mcp-server-health-monitor                                   | Generic uptime monitors                    |\n| ---------------------- | ----------------------------------------------------------- | ------------------------------------------ |\n| Probe method           | MCP `list_tools` call — tests actual protocol               | HTTP ping or TCP port check                |\n| Schema drift detection | Detects when tool signatures change between versions        | Not possible without protocol awareness    |\n| Config auto-discovery  | Reads Claude Desktop, Cursor, VS Code configs automatically | Manual URL entry per server                |\n| Data residency         | Local SQLite; no external service                           | Health data stored in vendor cloud         |\n| Cost                   | Free, self-hosted                                           | Free tier limited; paid for history/alerts |\n\nIf you want to know that your MCP servers are genuinely healthy — not just \"the process is running\" — this is the right tool.\n\n## Requirements\n\n- Node.js v20.19 or newer.\n- npm.\n\n## Getting started\n\nAdd the following config to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"health-monitor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-health-monitor@latest\"]\n    }\n  }\n}\n```\n\n> The monitor auto-discovers other MCP servers from the same config file it is registered in. No additional setup required.\n\n### MCP Client configuration\n\nAmp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed\n\n## Your first prompt\n\nEnter the following in your MCP client to verify everything is working:\n\n```\nCheck the health of all my MCP servers.\n```\n\nYour client should return a status table showing each server with its current latency and health state.\n\n## Tools\n\n### Health checks (3 tools)\n\n- `health_check_all` — probes all configured servers in parallel via `list_tools`, measures latency, and stores results. Accepts an optional `timeout_ms` parameter (default: 5000).\n- `get_server_status` — returns per-server detail including latency, last seen time, 24-hour error count, last error message, and p50/p95 latency percentiles. Requires `server_name`.\n- `list_degraded` — filters to servers that are offline or have latency above the threshold. Accepts an optional `latency_threshold` override.\n\n### History (1 tool)\n\n- `get_history` — returns raw health check history for a specific server, ordered most-recent first. Requires `server_name`; accepts optional `limit` (default: 50, max: 500).\n\n### Server registry (2 tools)\n\n- `configure_server` — registers a new MCP server to monitor. Servers added this way are stored in `~/.mcp/extra-servers.json` and merged with auto-discovered servers. Required: `name`, `command`. Optional: `args`, `env`.\n- `remove_server` — removes a manually registered server from monitoring. Only affects servers added via `configure_server`; auto-discovered servers are not affected. Requires `name`.\n\n### Updates (1 tool)\n\n- `check_updates` — detects version drift by hashing tool schemas on each probe and comparing against the last stored hash. Returns `has_changed`, `previous_hash`, `current_hash`, and `changed_at` per server.\n\n### Export (1 tool)\n\n- `export_dashboard` — generates a self-contained single-file HTML dashboard with summary cards, per-server status table with p50/p95 latency, and inline SVG uptime sparklines. Accepts an optional `output_path` to write to disk.\n\n## Manual server registry\n\nIn addition to auto-discovery from MCP config files, you can register servers that are not in your Claude Desktop config using the `configure_server` tool. Manually registered servers are written to `~/.mcp/extra-servers.json` (stored alongside the health database) and merged with auto-discovered servers on every probe.\n\n```\nAdd a server named \"my-internal-tool\" running with command \"node\" and args [\"/opt/tools/server.js\"]\n```\n\nTo stop monitoring a manually registered server:\n\n```\nRemove the server named \"my-internal-tool\" from monitoring\n```\n\nServers discovered from Claude Desktop's config cannot be removed via `remove_server` — edit your MCP config file directly to remove those.\n\n## Configuration\n\n### `--interval` / `--interval-seconds`\n\nHow often to poll each MCP server, in seconds.\n\nType: `number`\nDefault: `60`\n\n### `--latency-threshold`\n\nLatency in milliseconds above which a server is marked as degraded.\n\nType: `number`\nDefault: `1000`\n\n### `--db` / `--db-path`\n\nPath to the SQLite database file used to store health history.\n\nType: `string`\nDefault: `~/.mcp/health.db`\n\n### `--daemon`\n\nRun as a background polling daemon. Health data is collected continuously rather than on-demand.\n\nType: `boolean`\nDefault: `false`\n\n### `--startup-grace-seconds`\n\nGrace period in seconds before a newly started server is considered unhealthy.\n\nType: `number`\nDefault: `10`\n\nPass flags via the `args` property in your JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"health-monitor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-health-monitor@latest\", \"--interval=30\", \"--latency-threshold=500\"]\n    }\n  }\n}\n```\n\n## Listings\n\n- Listed on the [MCP Registry](https://registry.mcp.so) — search for `mcp-server-health-monitor`.\n- Listed on [MCP Market](https://mcpmarket.com) — search for `mcp-server-health-monitor`.\n\n## Verification\n\nBefore publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.\n\n**Interactive UI** (opens browser):\n\n```bash\nnpm run build && npm run inspect\n```\n\n**CLI mode** (scripted / CI-friendly):\n\n```bash\n# List all tools\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list\n\n# List resources and prompts\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list\n\n# Call a tool (example — replace with a relevant read-only tool for this plugin)\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name health_check_all\n\n# Call a tool with arguments\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name health_check_all --tool-arg key=value\n```\n\nRun before publishing to catch regressions in tool registration and runtime startup.\n\n## Contributing\n\nProbe modules live in `src/probes/`. Each probe must return a `ProbeResult` with `status`, `latencyMs`, and an optional `message`. Keep all probes read-only — never trigger side effects on monitored servers.\n\n```bash\nnpm install && npm test\n```\n",
  "bytes": 8170,
  "sha": "5fcf8368eaa3986ba8f0a1b8cb34f8bb4a8afc601eb9bbba9a9a08807bad3a34",
  "repo_slug": "dbsectrainer/mcp-server-health-monitor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dbsectrainer_mcp_server_health_ac298803/readme"
}