mcps

轻量 stdio MCP 服务器，作为日志记录和密钥注入门面，用于应提供给 AI 代理的服务。

服务器按需运行，由 MCP 主机（OpenCode、Hermes Agent、Codex 等）启动。凭据从本地配置文件读取，绝不会出现在工具结果中。

安装

uv sync

Related MCP server: mcp-homelab

配置

创建配置文件（默认 $XDG_CONFIG_HOME/mcps/config.toml），属主为运行用户，权限为 0600：

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

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

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

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

可通过 MCPS_* 环境变量或 CLI 标志覆盖单个值。优先级（从低到高）：文件 < 环境变量 < CLI。

注册到 MCP 主机

将 MCP 主机指向 mcps（或 python -m mcps）。以 OpenCode 为例（opencode.json 或 opencode.jsonc）：

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

以其他用户身份运行：

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

工具

• homeassistant_list_entities、homeassistant_get_state、homeassistant_call_service

• mealie_list_recipes、mealie_get_recipe、mealie_search_recipes

• nirvana_list_tasks、nirvana_get_task、nirvana_complete_task、nirvana_add_task

日志

纯文本日志位于 [server].log_file（默认 $XDG_STATE_HOME/mcps/mcps.log）。如果无法打开该文件，则回退到 stderr。

故障排查

• "config file not found" — 设置 --config 或 MCPS_CONFIG_PATH。

• "must have mode 0600" — 执行 chmod 600 <config>。

• "missing required keys" — 你的 [section] 缺少 url 或凭据。