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.

Install

uv sync

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 = "..."

Override individual values via MCPS_* environment variables or CLI flags. Precedence (low to high): file < env < CLI.

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

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.

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.