homelab-evidence-mcp
Collect read-only incident evidence from six homelab sources through MCP. One Go binary uses stdio and joins source identities through a configured .
Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
service_idThe server orders evidence by observation time. Each item includes its source,
timestamps, freshness, redaction count, and truncation state.
Correlation presents facts; it does not establish a root cause.
Destinations remain fixed after startup, and every upstream request uses HTTP GET.
Prerequisite: Go 1.26.10 is the minimum version.
go install github.com/ThomasCrouzet/homelab-evidence-mcp/cmd/homelab-evidence-mcp@latest
To build from the repository:
make build
./bin/homelab-evidence-mcp --version
config.example.yaml to a directory that is not in the repository.chmod 600 /path/config.yaml.
On Windows, use a user-only ACL.token_env or a private token_file.homelab-evidence-mcp --config /path/config.yaml --validate
Validation resolves token references and checks destination settings.
It sends no HTTP requests.
Unknown YAML keys cause an error. A base_url cannot contain query strings,
fragments, or userinfo. For Healthchecks, use a read-only API key.
Registration with an MCP client:
{
"mcpServers": {
"homelab-evidence": {
"command": "/path/homelab-evidence-mcp",
"args": ["--config", "/path/config.yaml"]
}
}
}
This example uses token files or inherited environment variables. The server reserves stdout for JSON-RPC and writes logs and audit events to stderr. It can also write a configured rotating audit file. See MCP client configuration and the integration example.
The server has these source adapters:
GET /api/v1/endpoints/statuses. It selects the
result with the greatest timestamp.GET /containers/json?all=true. It
filters fields and does not include Config.Env.GET /loki/api/v1/query_range. The configuration
supplies the selector.GET /api/v3/checks/. It uses a read-only
key and does not include ping URLs in its output.GET /api/systems and compatible routes. It can
give a host snapshot.GET /{topic}/json?poll=1&since=<unix>. The
configuration supplies the topic.Destinations use only http and https. For Docker, use a read-limited socket
proxy. The Docker Unix socket is not compatible with the server. The server
ignores HTTP_PROXY and HTTPS_PROXY.
You can use a path prefix in base_url. For example, use
https://proxy.example/gatus for Gatus. The server keeps /gatus before each
Gatus API route.
Set the source cache TTL with limits.source_cache_ttl.
The default is 15s; 0 disables it.
Cache keys use a process-local HMAC instead of clear-text authentication values.
Cache hits retain observed_at; retrieved_at records the new read time.
Thus, freshness reflects the snapshot's age.
evidence_capabilities gives the version, active sources, limits, and
statistics.list_services gives services in the canonical service registry.service_status gives a Gatus, Docker, Healthchecks, and Beszel snapshot.incident_context gives a multi-source timeline with configuration limits.search_logs examines Loki with the selector in the configuration.failed_crons gives checks in the down, grace, or paused state.get_evidence reads temporary evidence again by its opaque identifier.All tool annotations identify the tools as read-only. Global limits control windows, HTTP body sizes, evidence counts, and concurrency.
Each evidence item contains its source and its observation and collection
timestamps. It also contains severity, freshness state, truncation, and the
redaction count. Responses give the ok, absent, skipped, error, and
timeout state of each source.
See the evidence model and tested API contracts.
Read SECURITY.md for guarantees and remaining risks. The primary security controls are:
0600.go run ./demo
The demo uses local HTTP fixtures and an in-memory MCP session. It checks source errors, redaction, instruction markers, and GET-only requests. It does not start the stdio executable or contact a homelab.
Use make test-e2e to start the real stdio executable against six local HTTP
fixtures. This suite checks all seven MCP tools and all six adapters.
It does not contact live upstream services.
The runner saves a log and repeatable metadata outside the repository.
Set HEM_E2E_ARTIFACT_DIR to select the external artifact directory.
Set HEM_E2E_BINARY to the absolute path of a release binary.
make test # race detection and executable E2E tests
make test-e2e # executable stdio E2E tests
make test-quick # fast tests
make lint-docs # Markdown checks
make lint-private # private Tailscale address check
make lint # formatting, go vet, and golangci-lint
make coverage
make build
CI builds Linux, macOS, and Windows binaries. The primary targets are headless Linux and macOS systems.
MIT. See LICENSE.
Read-only stdio MCP server for cross-source homelab incident evidence (Gatus, Docker, Loki, Healthchecks).
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Homelab Evidence läuft lokal über stdio.
Zuletzt geprüft: 2026-10-28. Read-only stdio MCP server for cross-source homelab incident evidence (Gatus, Docker, Loki, Healthchecks).