# MCP Health Monitor **Category:** πŸ“Š Monitoring **Repository:** https://github.com/oaslananka/health-monitor-mcp **GitHub Stars:** 2 **npm Downloads (last month):** 482 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/mcp-health-monitor ## Description Monitor MCP server health, uptime, response times, and Azure DevOps pipeline status ## Tools Capabilities this server exposes over MCP: - **register_github_actions** β€” Register a GitHub Actions workflow by owner, repository, and workflow file or ID. Only the token environment-variable name is stored; token values remain in the runtime environment. - **check_github_actions** β€” Check the latest run for a registered GitHub Actions workflow and return failed job and step diagnostics. - **list_github_actions** β€” List registered GitHub Actions workflow targets and their latest status. - **unregister_github_actions** β€” Remove a GitHub Actions workflow target and its stored check history. - **register_gitlab_pipeline** β€” Register a GitLab CI/CD project pipeline. GitLab.com is allowed by default; self-hosted HTTPS origins require HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST. Only the token environment-variable name is stored. - **check_gitlab_pipeline** β€” Check the latest registered GitLab pipeline and return failed job, stage, ref, commit, URL, and bounded trace diagnostics. - **list_gitlab_pipelines** β€” List registered GitLab pipeline targets and their latest status. - **unregister_gitlab_pipeline** β€” Remove a GitLab pipeline target and its stored check history. - **register_http_target** β€” Register a GET-only HTTP or HTTPS endpoint with status, header, body, JSON, and TLS-expiry assertions. Public networks are allowed by default; private origins require full profile and HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST. - **check_http_target** β€” Check a registered HTTP target with DNS-pinned SSRF protection, bounded redirects/body reads, response assertions, and TLS-expiry diagnostics. - **list_http_targets** β€” List registered HTTP targets and their latest status, response, and TLS summary. - **unregister_http_target** β€” Remove an HTTP target and its stored check history. - **register_server** β€” Register an MCP server. Use http for a Streamable HTTP MCP endpoint, sse only for legacy Server-Sent Events servers, and stdio only for a local executable explicitly allowed by runtime policy. - **check_server** β€” Check the health of a registered MCP server, list tools, and measure response time. - **check_all** β€” Check all registered MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets with one bounded concurrency limit. Results preserve MCP-then-GitHub-then-GitLab-then-HTTP registration order; optional tags filter all target kinds. - **get_uptime** β€” Get uptime history and statistics for a registered MCP server. - **get_dashboard** β€” Get a dashboard overview of registered MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets with uptime and performance stats. - **get_report** β€” Get a human-readable Markdown health report for MCP servers, GitHub Actions workflows, GitLab pipelines, and HTTP targets. Paste directly into chat or docs. - **list_servers** β€” List all registered MCP servers with their current status. - **unregister_server** β€” Remove a server from monitoring. - **get_monitor_stats** β€” Get statistics about the health monitor itself, including database activity. - **set_alert** β€” Configure alert thresholds for response time, uptime, and consecutive failures. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "mcp-health-monitor": { "command": "npx", "args": ["-y","health-monitor-mcp"] } } ``` ## Documentation & README # health-monitor-mcp > MCP server, CI workflow, and generic HTTP endpoint monitoring with health history, TLS expiry, assertions, diagnostics, and operational reports. [![CI](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/oaslananka/health-monitor-mcp/graph/badge.svg)](https://codecov.io/gh/oaslananka/health-monitor-mcp) [![Release](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/oaslananka/health-monitor-mcp/actions/workflows/release.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/oaslananka/health-monitor-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/oaslananka/health-monitor-mcp) [![Node.js](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org) ## What This Does `health-monitor-mcp` keeps local registries of MCP servers, GitHub Actions workflows, GitLab pipelines, and generic HTTP endpoints. It performs live checks, records bounded evidence in SQLite, evaluates MCP alert thresholds, and returns JSON or Markdown diagnostics suitable for agents and operators. Supported target transports: - **Streamable HTTP** for current remote MCP servers. - **SSE** for legacy MCP servers. - **stdio** for trusted local executables after explicit opt-in. - **GitHub Actions** workflow runs, failed jobs, and failed steps for public or private repositories. - **GitLab CI/CD** pipelines, failed jobs, stages, refs, commits, URLs, and bounded trace excerpts for GitLab.com or allowlisted self-hosted instances. - **Generic HTTP/HTTPS** endpoints with status, header, body-substring, JSON-value, redirect, latency, and TLS-expiry checks. Azure DevOps monitoring was retired in v1.1.0. GitHub Actions shipped in v1.2.0 and GitLab CI/CD in v1.3.0; generic HTTP/TLS monitoring completes the current multi-provider feature line. ## Quick Start Run the published package noninteractively with Node.js 24: ```bash npx -y health-monitor-mcp --version ``` Example MCP client configuration: ```json { "mcpServers": { "health-monitor": { "command": "npx", "args": ["-y", "health-monitor-mcp"] } } } ``` ## Tools | Tool | Purpose | Typical prompt | | ---------------------------- | ------------------------------------------------------- | --------------------------------------- | | `register_server` | Register an MCP target | `Register inventory-prod` | | `check_server` | Run one MCP health check | `Check inventory-prod now` | | `register_github_actions` | Register a GitHub workflow | `Monitor ci.yml in owner/repo` | | `check_github_actions` | Check latest GitHub run and failed job/step diagnostics | `Check repo-ci now` | | `register_gitlab_pipeline` | Register a GitLab project pipeline | `Monitor group/project on GitLab` | | `check_gitlab_pipeline` | Check latest pipeline and bounded failed-job traces | `Check gitlab-ci now` | | `register_http_target` | Register a GET-only HTTP/HTTPS endpoint | `Monitor the public health endpoint` | | `check_http_target` | Check response assertions and TLS expiry | `Check service-health now` | | `register_webhook` | Register a webhook target for alert delivery | `Register alert-webhook for notifications` | | `test_webhook` | Send a test payload and return delivery diagnostics | `Test alert-webhook delivery` | | `check_all` | Check all target kinds with bounded concurrency | `Check all production targets` | | `get_uptime` | Return MCP uptime and latency history | `Show 24h uptime for inventory-prod` | | `get_dashboard` | Return a cross-provider JSON dashboard | `Give me a 24h dashboard` | | `get_report` | Return a cross-provider Markdown report | `Generate a 24h health report` | | `list_servers` | List registered MCP targets | `List monitored MCP servers` | | `list_github_actions` | List registered GitHub workflow targets | `List monitored workflows` | | `list_gitlab_pipelines` | List registered GitLab pipeline targets | `List monitored GitLab pipelines` | | `list_http_targets` | List registered HTTP targets | `List monitored HTTP endpoints` | | `list_webhooks` | List registered webhook targets | `List webhook targets` | | `unregister_server` | Remove an MCP target | `Stop monitoring local-debugger` | | `unregister_github_actions` | Remove a GitHub target and its history | `Stop monitoring repo-ci` | | `unregister_gitlab_pipeline` | Remove a GitLab target and its history | `Stop monitoring gitlab-ci` | | `unregister_http_target` | Remove an HTTP target and its history | `Stop monitoring service-health` | | `unregister_webhook` | Remove a webhook target and its history | `Stop monitoring alert-webhook` | | `set_alert` | Configure MCP health thresholds | `Alert if inventory-prod exceeds 500ms` | | `get_monitor_stats` | Inspect cross-provider monitor activity | `How many checks are stored?` | Expected configuration mistakes return stable error codes and remediation hints, including `SERVER_NOT_FOUND`, `GITHUB_ACTIONS_TARGET_NOT_FOUND`, `GITLAB_PIPELINE_TARGET_NOT_FOUND`, `GITLAB_BASE_URL_NOT_ALLOWED`, `HTTP_TARGET_NOT_FOUND`, `HTTP_TARGET_URL_NOT_ALLOWED`, `NO_SERVERS_REGISTERED`, `STDIO_DISABLED`, `STDIO_COMMAND_REJECTED`, `WEBHOOK_ENCRYPTION_KEY_REQUIRED`, `WEBHOOK_REGISTRATION_FAILED`, and `WEBHOOK_NOT_FOUND`. ## Register Targets Streamable HTTP: ```text register_server name="inventory-prod" type="http" url="https://inventory.example.com/mcp" tags=["production","inventory"] ``` Legacy SSE: ```text register_server name="legacy-search" type="sse" url="https://search.example.com/sse" tags=["legacy"] ``` Trusted local stdio: ```bash export HEALTH_MONITOR_ALLOW_STDIO=1 export HEALTH_MONITOR_STDIO_ALLOWLIST=npx,node ``` ```text register_server name="local-debugger" type="stdio" command="npx" args=["-y","mcp-debug-recorder"] tags=["local"] ``` The `command` field must contain one executable only. Put package names and flags in `args`. Remote-safe runtime profiles always disable stdio. ## Register GitHub Actions Public repositories can be checked without authentication. Private repositories and higher API rate limits require a token with Actions read access: ```bash export GITHUB_TOKEN=your-runtime-secret ``` ```text register_github_actions name="repo-ci" owner="oaslananka" repository="health-monitor-mcp" workflow="ci.yml" branch="main" token_env="GITHUB_TOKEN" tags=["production","ci"] check_github_actions name="repo-ci" timeout_ms=5000 ``` Only the environment-variable name in `token_env` is stored. The token value is read at check time and is never written to SQLite, logs, reports, or tool responses. ## Register GitLab Pipelines Public GitLab.com projects can be checked without authentication. Private projects require a token exposed only through the runtime environment: ```bash export GITLAB_TOKEN=your-runtime-secret ``` ```text register_gitlab_pipeline name="gitlab-ci" project="group/project" ref="main" token_env="GITLAB_TOKEN" tags=["production","ci"] check_gitlab_pipeline name="gitlab-ci" timeout_ms=5000 ``` GitLab.com is allowed by default. A self-hosted instance must use an HTTPS origin and be explicitly allowed: ```bash export HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST=https://gitlab.internal.example ``` ```text register_gitlab_pipeline name="private-gitlab" base_url="https://gitlab.internal.example" project="platform/service" token_env="GITLAB_TOKEN" ``` Only `token_env` is persisted. Token values, response bodies, and full traces are never stored or returned. Failed-job trace excerpts are range-requested, sanitized, and bounded. ## Register HTTP Targets Public HTTP and HTTPS endpoints are allowed by default. The provider sends GET requests only and supports bounded status, header, body-substring, JSON scalar, and TLS-expiry assertions: ```text register_http_target name="service-health" url="https://status.example.com/health" expected_statuses=[200] header_assertions=[{"name":"x-ready","equals":"yes"}] body_contains=["ready"] json_assertions=[{"path":"status","equals":"ready"}] tls_expiry_days=30 tags=["production","http"] check_http_target name="service-health" timeout_ms=5000 ``` Private, loopback, link-local, and other non-public addresses are blocked. A trusted private origin is available only in the `full` runtime profile and must be explicitly listed: ```bash export HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST=https://status.internal.example:8443 ``` Every DNS answer and every redirect destination is revalidated. Responses are capped at 262144 bytes; full response bodies and certificate chains are never stored or returned. ## Register Webhook Targets Webhook targets receive alert notifications via HTTPS POST with optional HMAC-SHA256 signing. Secrets are encrypted at rest when `HEALTH_MONITOR_WEBHOOK_ENCRYPTION_KEY` is configured (32+ characters); otherwise secret registration is rejected. ```text register_webhook name="alert-webhook" url="https://hooks.example/alerts" secret="webhook-secret" events=["down","alert"] tags=["production","alerts"] test_webhook name="alert-webhook" ``` Secrets are never returned in listings or diagnosticsβ€”always redacted. Delivery diagnostics include status, latency, HTTP status code, and error message. ## Health Checks and Reports ```text check_server name="inventory-prod" timeout_ms=5000 check_all timeout_ms=5000 tags=["production"] get_uptime name="inventory-prod" hours=24 get_dashboard hours=24 include_tool_stats=true get_report hours=24 ``` `HEALTH_MONITOR_MAX_CONCURRENCY` limits MCP, GitHub Actions, GitLab, and HTTP checks through one shared scheduled and interactive queue. Results preserve MCP-then-GitHub-then-GitLab-then-HTTP registration order even when checks complete out of order. ## Alerts ```text set_alert name="inventory-prod" max_response_time_ms=500 min_uptime_percent=99 consecutive_failures_before_alert=2 ``` Alert findings are evaluated by `check_server`, `check_all`, and `get_dashboard`. Configure webhook targets with `register_webhook` to receive alert notifications. ## Configuration | Variable | Default | Purpose | | ------------------------------------------ | --------------------------------- | ----------------------------------------------- | | `HEALTH_MONITOR_DB` | `~/.mcp-health-monitor/health.db` | SQLite database path | | `HEALTH_MONITOR_AUTO_CHECK` | `0` | Enable scheduled checks with `1` | | `HEALTH_MONITOR_RETENTION_DAYS` | `30` | Health-history retention | | `HEALTH_MONITOR_MAX_CONCURRENCY` | `5` | Scheduled and interactive check concurrency | | `GITHUB_TOKEN` | unset | Optional GitHub Actions read token | | `GITLAB_TOKEN` | unset | Optional GitLab project/pipeline/job read token | | `HEALTH_MONITOR_GITLAB_BASE_URL_ALLOWLIST` | unset | Allowed self-hosted GitLab HTTPS origins | | `HEALTH_MONITOR_HTTP_TARGET_ALLOWLIST` | unset | Private HTTP(S) origins allowed in full profile | | `HEALTH_MONITOR_ALLOW_STDIO` | `0` | Allow trusted local stdio checks | | `HEALTH_MONITOR_STDIO_ALLOWLIST` | unset | Optional comma-separated executable allowlist | | `HEALTH_MONITOR_HTTP_TOKEN` | unset | Bearer token for `POST /mcp` | | `HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST` | unset | Allowed remote client origins | | `HEALTH_MONITOR_HTTP_MAX_BODY_BYTES` | `1048576` | Maximum inbound MCP body | | `HEALTH_MONITOR_HTTP_BODY_TIMEOUT_MS` | `15000` | Inbound body read timeout | | `HEALTH_MONITOR_HTTP_STATEFUL_SESSIONS` | `0` | Enable stateful Streamable HTTP sessions | | `HEALTH_MONITOR_HTTP_SESSION_TTL_MS` | `1800000` | Stateful session TTL | | `HEALTH_MONITOR_HTTP_MAX_SESSIONS` | `100` | Stateful session cap | | `HEALTH_MONITOR_WEBHOOK_ENCRYPTION_KEY` | unset | 32+ char key for encrypting webhook secrets | | `HEALTH_MONITOR_WEBHOOK_TIMEOUT_MS` | `5000` | Webhook delivery timeout in milliseconds | ## HTTP Deployment The server binds to `127.0.0.1` by default. A non-loopback bind requires a remote-safe profile, bearer token, and Origin allowlist. ```bash HOST=0.0.0.0 \ HEALTH_MONITOR_PROFILE=remote-safe \ HEALTH_MONITOR_HTTP_TOKEN=change-me \ HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \ npx -y health-monitor-mcp-http ``` `GET /health` is unauthenticated and exposes only status and version. `POST /mcp` requires `Authorization: Bearer `. ## Docker Persist `/data`; otherwise the SQLite database disappears with the container. ```bash docker volume create health-monitor-data docker run --rm \ -v health-monitor-data:/data \ -p 127.0.0.1:3000:3000 \ -e HOST=0.0.0.0 \ -e HEALTH_MONITOR_PROFILE=remote-safe \ -e HEALTH_MONITOR_HTTP_TOKEN=change-me \ -e HEALTH_MONITOR_HTTP_ORIGIN_ALLOWLIST=https://client.example \ ghcr.io/oaslananka/health-monitor-mcp:latest ``` ## Development The repository pins Node.js 24.18.0 and pnpm 11.14.0 through `.mise.toml`. ```bash mise trust mise install pnpm install --frozen-lockfile pnpm run ci ``` Useful gates: ```bash pnpm run build pnpm run typecheck pnpm run lint pnpm run lint:test pnpm run test:coverage pnpm run test:integration pnpm run docs:api:check pnpm run security:supply-chain pnpm run check:metadata pnpm run check:package ``` ## Coverage and Test Analytics Jest remains the blocking coverage gate with repository-local thresholds. The CI validation job runs all unit and integration tests once, writes `coverage/lcov.info` and `reports/junit/junit.xml`, and uploads both reports to Codecov. Codecov project and patch statuses start as informational with `target: auto` and a 1% tolerance, adding pull-request diff coverage, file-level visibility, and failed-test analytics without duplicating the local merge gate. Codecov Bundle Analysis is intentionally not enabled. This package ships Node.js entrypoints compiled with `tsc`; it does not currently produce a Rollup, Vite, or Webpack application bundle whose download size is a product metric. ## Architecture and Roadmap - [Architecture](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/architecture.md) - [Operations](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/operations.md) - [Security](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/security.md) - [Usage](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/usage.md) - [Roadmap](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/ROADMAP.md) - [Release process](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/release.md) - [Generated API reference](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/api/README.md) ## Agent Runtime Configuration This repository owns its product-specific MCP configuration, plugin manifest, and skills: | File | Purpose | | ------------------------------ | ------------------------------------- | | `.claude-plugin/plugin.json` | Claude Code plugin manifest | | `.mcp.json` | Project-local MCP configuration | | `.codex/config.example.toml` | Codex CLI example | | `.vscode/mcp.example.json` | VS Code / Copilot example | | `opencode.example.jsonc` | OpenCode example | | `skills/` | Product-specific monitoring workflows | | `docs/agent-runtime-config.md` | Runtime setup and validation | ## Security and Contributing Report vulnerabilities through GitHub Private Vulnerability Reporting. See [SECURITY.md](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/SECURITY.md) and [docs/security.md](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/security.md). Contribution setup and standards are documented in [docs/contributing.md](https://github.com/oaslananka/health-monitor-mcp/blob/HEAD/docs/contributing.md). Usage questions belong in GitHub Discussions; actionable work belongs in issues. ## License MIT