mcps

Thin stdio MCP server acting as a logging and secret-injection facade for services that should be made available for AI agents.

The server runs on demand, launched by an MCP host (OpenCode, Hermes Agent, Codex, etc.). Credentials are read from a local config file and never appear in tool results.

Requires Python 3.12 or newer (the Garmin Connect SDK requires 3.12).

Install

uv sync

For development (tests and lint):

uv sync --extra dev

Related MCP server: mcp-homelab

Configure

Create the default config and log directory:

uv run mcps init

This creates ~/.mcps/config.toml and prepares ~/.mcps/logs. On POSIX, the config file is set to mode 0600, while ~/.mcps and its log directory are set to 0700. Running init again refuses to overwrite the config unless --force is supplied. Use mcps init --config <path> or MCPS_CONFIG_PATH to select another config path.

Edit the generated config to enable integrations:

[server]
log_file = "~/.mcps/logs/mcps.log"
log_level = "INFO"

[homeassistant]
url = "http://hass.local:8123"
token = "..."
verify_tls = false

[mealie]
url = "http://mealie.local:9000"
api_key = "..."

[netbox]
url = "https://netbox.example.com"
token = "..."

[nirvana]
url = "https://api.nirvanahq.com"
email = "..."
password = "..."

[garmin]
email = "user@example.com"
password = "..."
token_store = "~/.mcps/garmin"

Override individual values via MCPS_* environment variables or CLI flags. Precedence (low to high): file < env < CLI. For Garmin, the overrides are MCPS_GARMIN_EMAIL, MCPS_GARMIN_PASSWORD, and MCPS_GARMIN_TOKEN_STORE.

The config path can be overridden with MCPS_CONFIG_PATH or --config. The log path can be overridden with MCPS_SERVER_LOG_FILE or --log-file. On POSIX, mcps automatically corrects the config file to mode 0600 before reading it and fails if that is not possible or the file has another owner. On Windows, access is governed by the user's existing Windows ACLs.

Register with the MCP host

Point your MCP host at mcps (or python -m mcps). Example for OpenCode (opencode.json or opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcps": {
      "type": "local",
      "command": ["mcps"],
      "enabled": true
    }
  }
}

To run as a different user:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcps": {
      "type": "local",
      "command": ["sudo", "-u", "mcps", "-n", "mcps"],
      "enabled": true
    }
  }
}

Tools

• homeassistant_list_entities, homeassistant_get_state, homeassistant_call_service

• mealie_list_recipes, mealie_get_recipe, mealie_search_recipes

• netbox_get - read an unescaped REST API path below /api/ with optional query parameters

• nirvana_list_tasks, nirvana_get_task, nirvana_complete_task, nirvana_add_task

• garmin_get_daily_summary, garmin_get_sleep, garmin_get_heart_rate, garmin_get_stress, garmin_get_body_battery, garmin_list_activities, garmin_get_activity

mealie_list_recipes and mealie_search_recipes return one page at a time and accept limit (default 20, maximum 100) and page (default 1).

netbox_get only sends GET requests, refuses redirects, and blocks the NetBox token administration endpoint. Use a NetBox token belonging to a user with the minimum required read-only object permissions. Generic API responses can contain sensitive custom fields or plugin data that mcps cannot identify automatically.

Upstream response bodies are capped at 1 MiB; a larger response fails instead of being truncated. Compressed responses are refused so the decoded size stays bounded. Tool results never contain a configured credential: every parsed response is redacted, and upstream errors are replaced with a safe message that is itself checked against the configured credentials.

Garmin Connect

Garmin Connect has no public consumer API. This integration uses the unofficial garminconnect SDK for Garmin's mobile SSO flow, and Garmin can change or block those endpoints without notice. It only reads health and activity data; it never writes to the account. The data (sleep, heart rate, stress, activities) is sensitive, and the cached tokens grant persistent account access until revoked in Garmin's account security settings.

Authenticate once before using the tools:

uv run mcps --config ~/.mcps/config.toml garmin-login

If Garmin requires MFA, the command prompts for the one-time code on the terminal. Tokens are stored in token_store (default ~/.mcps/garmin) with mode 0700 for the directory and 0600 for garmin_tokens.json; mcps refuses to start if the path is a symlink or owned by another user. The MCP server never prompts for MFA, so re-run garmin-login if authentication fails.

The Garmin SDK manages its own HTTP layer, so http_timeout and verify_tls=false do not apply: TLS verification is always required. Dates are YYYY-MM-DD; garmin_get_body_battery accepts at most 31 days per call, and garmin_list_activities returns at most 100 activities per call. Garmin calls are serialized, and generated OAuth tokens and cookies are redacted from tool results alongside the configured credentials.

Logs

Flat-text log at [server].log_file (default ~/.mcps/logs/mcps.log). Falls back to stderr if the file cannot be opened.

Troubleshoot

• "config file not found" — set --config or MCPS_CONFIG_PATH.

• "could not be changed to 600" — ensure the current user can change the config file.

• "missing required keys" — your [section] lacks url or credentials.

• Garmin "authentication failed; run mcps garmin-login" — the cached tokens expired or were revoked; re-run mcps garmin-login.

• Garmin "token store could not be secured" — fix ownership/mode of token_store (or remove a symlinked path) and retry.