trmm-mcp

Сервер MCP только для чтения — MCP, который предоставляет инстанс Tactical RMM как инструменты агента, чтобы LLM могла получать данные об устройствах, клиентах и аудите — без возможности что-либо изменить.

• Только чтение: заложено в архитектуру. Не реализованы инструменты run-script, run-command, reboot, install, edit, create или delete. Даже если API-ключ поддерживает запись, радиус поражения нулевой. Всё равно используйте его с сервисным пользователем только для чтения (защита в глубину).

• Python + FastMCP. Два транспорта из одной кодовой базы: stdio для локального использования в вашем MCP-клиенте и Streamable HTTP (с общей аутентификацией через bearer-токен) для общего удалённого сервера, к которому подключается вся команда — см. Удалённое развёртывание.

• Конфигурация — только через переменные окружения — никаких секретов в коде. При запуске быстро завершается с ошибкой, если обязательные переменные отсутстствуют.

Tools

Все инструменты имеют readOnlyHint: true, DestructiveHint: false, Id empotentHint: true, openWorldHint: true, возвращают структурированный контент со схемой вывода и поддерживают пагинацию там, где применимо.

Точные эндпоинты и payload журнала аудита: docs/API_CONTRACT.md.

Related MCP server: KVMFleet MCP Server

Configuration

Получите API-ключ в TRMM: Settings → Global Settings → API Keys (выберите своего сервисного пользователя только для чтения). Ключ обходит 2FA и наследует права роли этого пользователя.

Install

Требуется 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.)

Run

Сервер общается через MCP по stdio, поэтому обычно его запускает ваш MCP-клиент. Чтобы запустить вручную (будет ждать MCP-клиент на stdin):

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

Если TRMM_API_URL/TRMM_API_KEY отсутствуют, выезжает ясное сообщение об ошибке в stderr и завершается с ненулевым кодом.

Register with an MCP client (stdio)

Claude Code — project .mcjson.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. После редактирования перезапустите приложение.

Remote deployment (доступ всей команды)

Запустите trmm-mcp как общий HTTPS-сервер, чтобы инженеры/поддержка использовали его как Claude connector вместо установки локально. Ключ API TRMM остаётся на стороне сервера; клиенты аутентифицируются через общий bearer-токен.

1. Generate bearer token and configure

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>

Сервер откажется запуститься в http-режиме без TRMM_MCP_AUTH_TOKEN.

2. Deploy to Docker / Portainer

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

В Portainer разверните стек из этого репозитория и задайте переменные окружения в стеке — он подходит под ваш существующий процесс build → push → повторного развертывания через webhook Portainer. Образ работает в непривеличенном пользователе (non-root) и включает Docker HEALTHCHECK для /healthz.

3. Поместите за HTTPS и сетевой шлюз

Terminate TLS and шлюзируйте доступ перед контейнером через reverse proxy (Caddy/Nginx/Traefik) на клике https://trmm-mcp.example.com, за VPN или Cloudflare Access. Bearer-токен это не единственный слой, а просто extra. **Никогда не выставляйте порт 8080 в интернет без аутентификации.

4. Connect Claude (Claude Code / Desktop)

Remote .mcp.json — на машине коллеги не нужны Python, репозиторий или ключ TRMM:

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

claude.ai web и мобильные

Web/mobile ствой for custom connector uses OAuth, а не статический заголовок — таким образом, bearer-настройка выше охватывает Claude Code + Desktop. Для web и мобильных поставьте перед сервером Cloudflare Tunnel + MCP Server Portal: он выполняет OAuth/SSO (Entra) flow для Claude и впрыскивает bearer-токен upstream, поэтому достаточно кода сервера не требуется. Полное руководство: docs/REMOTE_OAUTH_CLOUDFLARE.md. Используются docker-compose.cloudflare.yml (sidecar для туннеля, порты не публикуются).

Endpoints

Test with MCP Inspector

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

Then in Inspector UI: list tools, call trmm_list_clients, and try trmm_search_audit_log with within_days: 7 to verify pagination and audit-log filters work against live data.

Evaluation

evaluation.xml contains 10 read-only questions for MSP with verified answers. Run them with the harness from the mcp-builder skill:

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

Ответы in evaluation.xml are specific to the instance they were verified against; regenerated for the different dataset.

Security notes

• Secrets только из окружения; на stdout ничего не выводится (stdio-серверы должны держать stdout чистым — диагностика только в stderr).

• Ошибки переводятся в выполняемое действие и разделяют auth (401), perms (403), not-found (404), network/timeout, не раскрывая internals.

• Этodтер server никогда не вызывает мутирующих endpoint. A future explicitly-gated action server would be a separate project.