trmm-mcp

一个只读的 MCP 服务器，将 Tactical RMM 实例暴露为 agent 工具，使 LLM 能够获取设备、客户端和审计数据——而没有任何更改能力。

• 按理设计就是只读。 未实现任何 run-script、run-command、reboot、install、edit、create 或 delete 工具。即使 API 密钥具有写权限，影响范围也为零。请务必同时搭配一个只读的 service user（纵深防御）。

• Python + FastMCP。同一套代码支持两种传输：stdio 用于本地 MCP 客户端，Streamable HTTP（带共享 bearer-token 认证）用于团队连接的共享远程服务器——参见远程部署。

• 配置只从环境变量读取——代码中不存机密。如果必需的变量缺失，启动时会快速失败。

工具

所有工具均为 readOnlyHint: true、destructiveHint: false、idempotentHint: true、openWorldHint: true，返回带输出模式的结构化内容，并在适用条件下支持分页。

参见 docs/API_CONTRACT.md 了解具体接口和审计日志载荷。

Related MCP server: KVMFleet MCP Server

配置

在 TRMM 中获取 API key：Settings → Global Settings → API Keys（选择你的只读服务用户）。该 key 会绕过 2FA 并继承该用户的角色权限。

安装

需要 Python 3.10+。

cd tactical-rmm-mcp
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

（或运行 pip install -e . 获得 trmm-mcp 命令。）

运行

该服务器通过 stdio 使用 MCP 协议，通常由你的 MCP 客户端启动。要手动运行（它会等待 stdin 上有 MCP 客户端）：

# set env first, then:
python -m trmm_mcp
# or
python server.py

如果缺少 TRMM_API_URL 或 TRMM_API_KEY，它会在 stderr 中打印清晰的错误并以非零状态退出。

在 MCP 客户端中注册（stdio）

Claude Code —— 项目的 .mcp.json

在你的项目中创建 .mcp.json（使用 server.py 的绝对路径，以及你虚拟环境中的 Python，以便依赖能够解析）：

{
  "mcpServers": {
    "trmm": {
      "command": "C:\\Users\\admin\\your-workspace\\tactical-rmm-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\admin\\your-workspace\\tactical-rmm-mcp\\server.py"],
      "env": {
        "TRMM_API_URL": "https://api.yourdomain.com",
        "TRMM_API_KEY": "your-readonly-key",
        "TRMM_MON_TOKEN": "optional-mon-token"
      }
    }
  }
}

Claude Desktop —— claude_desktop_config.json

结构相同，放在顶层的 "mcpServers" 键下：

{
  "mcpServers": {
    "trmm": {
      "command": "/abs/path/tactical-rmm-mcp/.venv/bin/python",
      "args": ["/abs/path/tactical-rmm-mcp/server.py"],
      "env": {
        "TRMM_API_URL": "https://api.yourdomain.com",
        "TRMM_API_KEY": "your-readonly-key"
      }
    }
  }
}

在 macOS 上，这个文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上位于 %APPDATA%\Claude\claude_desktop_config.json。编辑后重启应用。

远程部署（团队成员共同访问）

将 trmm-mcp 作为共享 HTTPS 服务器运行，这样工程师 / 服务台成员将其用作 Claude 连接器，而不必每个人都本地安装一份。TRMM API key 保留在服务器上；客户端用共享的 bearer token 进行认证。

1. 生成 bearer token 并配置

python -c "import secrets; print(secrets.token_urlsafe(32))"

在 .env（或你的 Portainer 栈环境）中：

TRMM_API_URL=https://api.yourdomain.com
TRMM_API_KEY=<read-only service-user key>
TRMM_MCP_TRANSPORT=http
TRMM_MCP_AUTH_TOKEN=<the token you just generated>

如果没有 TRMM_MCP_AUTH_TOKEN，服务器在 http 模式下会拒绝启动。

2. 用 Docker / Portainer

docker compose up -d --build
curl http://localhost:8080/healthz        # -> {"status":"ok",...}

在 Portainer 中从这个仓库部署一个 stack，并在该 stack 上设置环境变量——与现有的 build → push → Portainer webhook 重新部署流程一致。镜像以非 root 用户运行，并带有其对 /healthz 的 Docker HEALTHCHECK。

3. 放到 HTTPS + 一个网络门禁后面

在容器前面终止 TLS 并控制访问权限——推荐使用反向代理（Caddy / Nginx / Traefik）提供例如 https://trmm-mcp.example.com，放在 VPN 或 Cloudflare Access 后面。bearer token 只是纵深防御的一层，不是唯一防线。切勿将 8080 端口未经认证直接暴露到公网。

4. 连接 Claude（Claude Code / Desktop）

远端的 .mcp.json —— 成员电脑上无需 Python、代码仓库或 TRMM key：

{
  "mcpServers": {
    "trmm": {
      "type": "http",
      "url": "https://trmm-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <shared-token>" }
    }
  }
}

claude.ai 网页版和移动端

网页 / 移动端自定义连接器 UI 使用 OAuth 认证，而不是静态 header —— 因此上面的 bearer token 方案覆盖的是 Claude Code + Desktop 的。对于网页版和移动端，在服务器前再套一层 Cloudflare Tunnel + 一个 MCP Server Portal：它会向 Claude 完成 OAuth/SSO（Entra）流程，并在上游注入 bearer token，所以不需要额外的服务器代码。完整步骤：docs/REMOTE_OAUTH_CLOUDFLARE.md。使用docker-compose.cloudflare.yml（带有 sidecar，不发布端口）。

端点

用 MCP Inspector 测试

npx @modelcontextprotocol/inspector \
  -e TRMM_API_URL=https://api.yourdomain.com \
  -e TRMM_API_KEY=your-readonly-key \
  -- python server.py

然后在 Inspector UI 中：列出工具，调用 trmm_list_clients，再尝试 trmm_search_audit_log 并传入 within_days: 7，确认分页和审计日志过滤器在实时数据上工作正常。

评测

evaluation.xml 包含 10 个只读 MSP 相关的问题，并带验证过的答案。使用随 mcp-builder 技能提供的测试工具运行它们：

python scripts/evaluation.py \
  -t stdio -c python -a server.py \
  -e TRMM_API_URL=https://api.yourdomain.com \
  -e TRMM_API_KEY=your-readonly-key \
  -o evaluation_report.md \
  evaluation.xml

evaluation.xml 中的答案是针对其验证时的那个实例；换用不同数据集时需要重新生成。

安全说明

• 所有机密都只来自环境变量；不向 stdout 记录任何内容（stdio 服务器必须保持 stdout 干净——诊断请写到 stderr）。

• 错误会被转化为可操作的提示，区分认证（401）、权限（403）、未找到（404）、网络/超时等（404）等情况，且不泄露内部实现。

• 此服务器不会调用任何会改变状态的 API。将来如果需要类似有修改能力的动作服务器，那将是另一个独立项目的范畴。