trmm-mcp

Un servidor MCP de solo lectura que expone una instancia de Tactical RMM como herramientas de agente, para que un LLM pueda recopilar datos de dispositivos, clientes y auditoría, sin ninguna capacidad de modificar nada.

• Solo lectura por diseño. No se implementan herramientas de ejecutar script, ejecutar comando, reiniciar, instalar, editar, crear o eliminar. Incluso si la clave de API tuviera permisos de escritura, el radio de impacto es cero. Acompáñalo de todos modos con un usuario de servicio de solo lectura (defensa en profundidad).

• Python + FastMCP. Dos transportes desde un mismo código: stdio para uso local bajo tu cliente MCP, y HTTP Streamable (con autenticación compartida por token Bearer) para un servidor remoto compartido al que se conecta todo el equipo; consulta Despliegue remoto.

• La configuración es solo mediante variables de entorno — sin secretos en el código. Falla rápidamente al inicio si faltan variables obligatorias.

Herramientas

Todas las herramientas tienen readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, devuelven contenido estructurado con un esquema de salida y admiten paginación cuando corresponde.

Consulta docs/API_CONTRACT.md para conocer los endpoints exactos y la carga útil del registro de auditoría.

Related MCP server: KVMFleet MCP Server

Configuración

Obtén una clave de API en TRMM: Configuración → Configuración global → Claves de API (elige tu usuario de servicio de solo lectura). La clave omite la 2FA y hereda los permisos de rol de ese usuario.

Instalación

Requiere 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

(O pip install -e . para obtener el script de consola trmm-mcp.)

Ejecución

El servidor habla MCP a través de stdio, por lo que normalmente lo inicia tu cliente MCP. Para ejecutarlo manualmente (esperará a un cliente MCP en stdin):

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

Si faltan TRMM_API_URL/TRMM_API_KEY, imprime un error claro en stderr y sale con código distinto de cero.

Registrar con un cliente MCP (stdio)

Claude Code — .mcp.json del proyecto

Crea .mcp.json en tu proyecto (usa la ruta absoluta a server.py y el Python de tu venv para que las dependencias se resuelvan):

{
  "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

Misma forma, bajo la clave de nivel superior "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"
      }
    }
  }
}

En macOS este archivo se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json; en Windows en %APPDATA%\Claude\claude_desktop_config.json. Reinicia la aplicación después de editarlo.

Despliegue remoto (acceso para el equipo)

Ejecuta trmm-mcp como un servidor HTTPS compartido para que los ingenieros/mesa de ayuda lo usen como conector de Claude en lugar de instalarlo localmente cada uno. La clave de API de TRMM permanece en el servidor; los clientes se autentican con un token Bearer compartido.

1. Genera un token Bearer y configura

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

En .env (o en las variables de entorno de tu stack de 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>

El servidor se niega a iniciar en modo http sin TRMM_MCP_AUTH_TOKEN.

2. Despliega con Docker / Portainer

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

En Portainer, despliega un stack desde este repositorio y establece las variables de entorno en el stack; se ajusta a tu flujo existente de compilar → publicar → redesplegar mediante webhook de Portainer. La imagen se ejecuta como usuario no root e incluye un HEALTHCHECK de Docker contra /healthz.

3. Ponlo detrás de HTTPS + una puerta de red

Termina TLS y controla el acceso delante del contenedor: un proxy inverso (Caddy/Nginx/Traefik) que sirva, por ejemplo, https://trmm-mcp.example.com, detrás de tu VPN o Cloudflare Access. El token Bearer es defensa en profundidad, no la única capa. Nunca expongas el puerto 8080 a internet sin autenticación.

4. Conecta Claude (Claude Code / Desktop)

.mcp.json remoto — sin Python, repositorio ni clave de TRMM en la máquina del compañero:

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

claude.ai web y móvil

La interfaz de conector personalizado web/móvil autentica mediante OAuth, no con una cabecera estática — por lo que la configuración Bearer anterior cubre Claude Code + Desktop. Para web y móvil, coloca delante del servidor Cloudflare Tunnel + un Portal de servidores MCP: ejecuta el flujo OAuth/SSO (Entra) hacia Claude e inyecta el token Bearer aguas arriba, por lo que no se necesita código adicional en el servidor. Guía completa: docs/REMOTE_OAUTH_CLOUDFLARE.md. Usa docker-compose.cloudflare.yml (sidecar de túnel, sin puertos publicados).

Endpoints

Probar con MCP Inspector

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

Luego, en la interfaz del Inspector: lista las herramientas, llama a trmm_list_clients y prueba trmm_search_audit_log con within_days: 7 para confirmar que la paginación y los filtros del registro de auditoría funcionan con datos reales.

Evaluación

evaluation.xml contiene 10 preguntas de MSP de solo lectura con respuestas verificadas. Ejecútalas con el arnés incluido en la habilidad 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

Las respuestas en evaluation.xml son específicas de la instancia contra la que se verificaron; regenéralas para un conjunto de datos diferente.

Notas de seguridad

• Los secretos provienen solo del entorno; nada se registra en stdout (los servidores stdio deben mantener stdout limpio — los diagnósticos van a stderr).

• Los errores se traducen a mensajes accionables que distinguen autenticación (401) vs. permisos (403) vs. no encontrado (404) vs. red/tiempo de espera, sin filtrar detalles internos.

• Este servidor nunca llama a un endpoint de mutación. Un futuro servidor de acciones, explícitamente restringido, sería un proyecto separado.