homelab-evidence-mcp
About
Read-only stdio MCP server that correlates homelab incident evidence across Gatus, Docker, Loki, Healthchecks, Beszel, and ntfy. Destinations locked at startup; HTTP GET only; timelines stay factual without inventing root cause.
Details
- Author
- thomascrouzet
- Categories
- Other
Jump to
Setup
Install homelab-evidence-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/thomascrouzet/homelab-evidence-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Local MCP server overstdiotransport that gathers incident evidence from a homelab. It ships as a static Go binary and offers no mutation operations.
When a service fails, the signals are scattered:
- Gatus reports an error;
- Docker shows a container restarting;
- Loki contains a timeout a few moments earlier;
- Healthchecks shows a scheduled job failing.
Specialized tools correctly expose their own source, but they share neither a service identity, nor a common evidence format, nor a shared timeline. This project provides that correlation layer without inventing causality.
- Canonical registry: an explicitservice_idlinks Gatus, Docker, Loki, Healthchecks, Beszel, and ntfy identities.
- Common evidence model: every item is bounded, timestamped, attributed, redacted, and marked when truncated.
- Deterministic correlation: the timeline presents facts; it does not claim to establish a root cause.
- Structural read-only: only HTTPGETrequests to destinations locked at startup are allowed.
02:12 Loki upstream timeout [REDACTED] 02:13 Docker container media is restarting 02:14 Gatus media/app failure status=503 02:15 Healthchecks "media-cron" is down Timeline is ordered by observed_at; correlation does not establish root cause.
This server is neither a dashboard, nor a generic HTTP proxy, nor a control plane. It restarts no container and produces no root-cause analysis.
go install github.com/ThomasCrouzet/homelab-evidence-mcp/cmd/homelab-evidence-mcp@latest
make build ./bin/homelab-evidence-mcp --version
- Copyconfig.example.yamlto a private location.
- Restrict the file to the owner:chmod 600 /path/config.yamlon Unix, or a user-only ACL on Windows.
- Fill in internal URLs and a few pilot services.
- Export required tokens, for exampleHEALTHCHECKS_API_TOKEN.
- Validate the configuration before wiring it into the MCP client.
homelab-evidence-mcp --config /path/config.yaml --validate
Validation loads tokens and locks destinations from the YAML; it does not probe them with HTTP. It fails on any unknown YAML key. Query strings, fragments, and userinfo are forbidden inbase_url; authentication usestoken_envortoken_file.
{ "mcpServers": { "homelab-evidence": { "command": "/path/homelab-evidence-mcp", "args": ["--config", "/path/config.yaml"], "env": { "HEALTHCHECKS_API_TOKEN": "readonly-key" } } } }
Standard output is reserved for the JSON-RPC protocol. Logs and audit events are written to standard error. SeeMCP client configurationand theintegration example.
Destinations accept onlyhttpandhttps. For Docker, use a read-limited socket proxy; the direct Unix socket is not supported.HTTP_PROXYandHTTPS_PROXYare ignored.
A path prefix is allowed inbase_url:https://proxy.example/gatusis correctly combined with Gatus routes.
The source response cache (limits.source_cache_ttl, default15s,0to disable) briefly memorizes identical requests. Authentication values are never stored in clear text in its keys; a process-local HMAC fingerprint distinguishes access secrets. On a hit,observed_atkeeps the original collection time andretrieved_atmarks the current read; freshness therefore reflects the real age of the snapshot.
All tools are annotated as read-only. Global limits bound windows, HTTP bodies, evidence counts, and concurrency.
Each evidence item includes its source, observation timestamp, collection timestamp, severity, freshness state, any truncation, and the number of redactions applied. Responses also report sources that succeeded, were absent, skipped, errored, or timed out.
See theevidence modelandtested API contracts.
Guarantees and residual risks are detailed inSECURITY.md. Key points:
- destinations locked at startup;
- HTTP redirects refused;
- no URL or stream selector supplied by an MCP call;
- log content treated as hostile data;
- built-in redaction and optional local rules;
- configuration and token files limited to mode0600on Unix. On Windows, apply a user-only ACL; the binary does not inspect Windows ACLs.
The demo starts test HTTP servers, opens an in-memory MCP session, verifies partial results, redaction, and the complete absence of non-GETrequests. No real homelab is required.
make test # tests with race detection make test-quick # fast tests make lint # formatting, go vet, and golangci-lint if available make coverage make build
The project builds Linux, macOS, and Windows binaries in CI. Primary targets remain headless Linux and macOS systems.
Transaction-complete hotel booking over MCP — 300K+ properties, real hotel confirmation numbers, loyalty points, secure checkout. Hotels are merchant of record. Builders set their own booking fee via Stripe Connect. Built on proven distribution infrastructure.
An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..
Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.
ALTER - identity infrastructure for the AI economy
D2C eCommerce fulfillment platform: manage orders, inventory, shipments, campaigns, and billing via AI agents
Apigene MCP Gateway is the runtime layer that connects AI agents to APIs and MCP servers via Model Context Protocol.
MCP to interface with multiple blockchains, staking, DeFi, swap, bridging, wallet management, DCA, Limit Orders, Coin Lookup, Tracking and more.
MCP server for Bitnovo Pay integration with AI agents. Provides cryptocurrency payment capabilities through Bitnovo Pay API. Features include payment creation, status checking, QR code generation, and webhook management with support for multiple tunnel providers (ngrok, zrok, manual).
Shop for gift cards, esims, phone topups. Pay with cards and crypto.
You built it, now get users! GoToMarket MCP server
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
