{
  "markdown": "<!-- mcp-name: io.github.shin2344234/trmm-mcp -->\n\n# TacticalRMM MCP server\n\nLets an AI assistant read everything in your TacticalRMM install, and — when\nyou explicitly switch it on — run commands on your managed machines.\n\nAsk \"which machines are offline and why\", \"what's eating memory on the front\ndesk PC\", \"show me every failed check this week\", and get answers from live\nfleet data. Turn on `elevate` mode and the assistant can also fix things, but\nonly after you approve each action yourself.\n\n## Why I built it\n\nI manage machines for a number of clients, and TacticalRMM already collects far\nmore about each one than anyone has time to sit and read. I wanted to actually\nuse that data: run deeper diagnostics than the dashboard puts in front of you,\nproduce per-client reports covering every device, and find the things worth\nfixing before someone rings up to report them.\n\nIt does grow billable work, and I think that is fine as long as the work is\nreal. A disk throwing early SMART errors, a server quietly filling up, patches\nthat stopped applying three months ago and nobody noticed — catching those is\nworth paying for. Billing for busywork is not. The test I hold this to is\nwhether every item on a report is something the client can see the sense in\nfixing once it has been explained to them.\n\n## What you get\n\n**28 tools.** 20 read-only ones covering agents, checks, alerts, services,\nprocesses, event logs, software inventory, patches, scripts and audit history;\n8 execution tools for running commands and scripts, rebooting, controlling\nservices, killing processes, and waking machines.\n\n**A full audit trail of everything.** Every inbound request, every tool call\nwith its arguments, every result, every TRMM API call, every approval decision\nand every refusal is written to a structured JSONL log with credential\nredaction and rotation. For a bridge that can run commands as SYSTEM across a\nfleet, knowing exactly who asked for what and when is not optional — so it is\non by default and cannot be silently skipped. Details in\n[Audit logging][audit-log].\n\n**An approval gate the model cannot reach.** In `elevate` mode an execution is\nrefused until you approve that exact call in a browser (password + TOTP) or\nfrom a shell on the server. Approvals are bound to a fingerprint of the\narguments, are single-use, and expire. No tool exists that grants elevation.\n\n**Read-only that actually holds.** Three independent layers: the execution\ntools are never registered, the HTTP client refuses non-read requests, and the\nAPI key itself is bound to a TRMM role with no execution permissions.\n\n**Built for real fleets.** TRMM has no pagination and returns whole tables —\none agent detail call measured 192 KB here. Responses are projected, capped and\ntruncated with an explicit notice, so a single call cannot swallow the model's\ncontext.\n\n**HTTPS with bearer auth**, a self-signed certificate carrying an IP SAN, and a\nhardened systemd unit. Clients trust that one certificate rather than skipping\nverification.\n\nWorks with Claude Code, Claude Desktop and LM Studio on macOS, Windows and\nLinux. Built and verified against **TRMM 1.5.1**. The TRMM API itself is\ndocumented independently in [docs/trmm-api.md][trmm-api].\n\n---\n\n## Three modes\n\n| | `readonly` (default) | `elevate` | `command` |\n|---|---|---|---|\n| Tools exposed | 20 read tools | 28 | 28 |\n| Reads | yes | yes | yes |\n| Executions | **never** | **only what you approve, one call at a time** | always |\n| TRMM key for reads | `mcp-readonly` | `mcp-readonly` | `mcp-command` |\n| TRMM key for executions | — | `mcp-command`, only after approval | `mcp-command` |\n| Good for | pure Q&A | day-to-day chat | unattended automation |\n\n`elevate` is the one to use for interactive work: Claude can look at anything,\nbut the moment it wants to *do* something it stops and waits for you.\n\n## Security\n\nThe short version:\n\n- **The approval gate is out of band.** In `elevate` mode an execution is\n  refused until you approve that exact call in a browser (password + TOTP) or\n  from a shell on the server. Approvals are bound to a fingerprint of the\n  arguments, are single-use, and expire. No tool exists that grants elevation,\n  so the model has no route to its own approval.\n- **Read-only holds at three independent layers.** The execution tools are\n  never registered, the HTTP client refuses non-read requests, and the API key\n  itself is bound to a TRMM role with no execution permissions.\n- **Destructive patterns are refused client-side** in `command` mode — `rm -rf\n  /`, `mkfs`, `dd of=/dev/*`, `format c:` and the rest — with an optional agent\n  allowlist to hard-scope what can be touched at all.\n- **HTTPS with bearer auth**, a self-signed certificate carrying an IP SAN, and\n  a hardened systemd unit. Clients trust that one certificate rather than\n  skipping verification.\n\nThere is one honest caveat about the third read-only layer, because TRMM has no\nview-only permission for services, processes or Windows updates. That, the\napproval page's own password + TOTP gate, and why MCP elicitation is not used as\nthe approval channel, are all written up in **[docs/security.md][security]**.\n\n## Setup\n\nAlready done on this box:\n\n- venv at `venv/` with `mcp` 2.0 and `httpx`\n- TRMM roles `MCP Read Only` and `MCP Command`, users `mcp-readonly` and\n  `mcp-command` (both blocked from UI login, unusable passwords)\n- API keys written to `.env` (mode 600)\n\nTo re-provision or rotate keys:\n\n```bash\n/rmm/api/env/bin/python /opt/trmm-mcp/provision_trmm_accounts.py --rotate\n```\n\n## Running the server\n\nTo reach it from other machines, first tell it which address to serve on. These\ngo in `.env`, not in the unit file — the unit is in git, and an address baked in\nthere would follow every copy of it onto the wrong machine:\n\n```bash\ncat >> /opt/trmm-mcp/.env <<'EOF'\nTRMM_MCP_HTTP_HOST=10.0.0.5\nTRMM_MCP_PUBLIC_URL=https://10.0.0.5:8770\nEOF\n```\n\nSubstitute your own address. `TRMM_MCP_PUBLIC_URL` is what the assistant tells\nyou to open when something needs approving, so it has to be a URL your browser\ncan actually reach. Skip this step and the server binds `127.0.0.1`, which is\nfine if the client runs on the same box.\n\nThen install the unit and start it:\n\n```bash\nsudo cp /opt/trmm-mcp/trmm-mcp.service /etc/systemd/system/ && sudo systemctl daemon-reload && sudo systemctl enable --now trmm-mcp\n```\n\nCheck what it came up on — the startup line names the address, the mode and\nwhether TLS is on:\n\n```bash\njournalctl -u trmm-mcp -n 5 --no-pager | grep listening\n```\n\nIt serves HTTPS on port 8770 by default and requires the bearer token from\n`.env`. To run it in the foreground instead, for a quick test:\n\n```bash\n/opt/trmm-mcp/run.sh readonly http\n```\n\nThe listener runs stateless (`TRMM_MCP_STATELESS_HTTP=true`, the default). This\nmatters: with stateful streamable HTTP the server hands out a session id that\ndies with the process, so restarting the service leaves any connected client\nreplaying a session the server has forgotten. Through `mcp-remote` that shows up\nas tool calls hanging for minutes and then failing, while `tools/list` still\nanswers, with `Rejected request with unknown or expired session ID` in\n`logs/server.log`. Stateless removes the failure mode; we use no\nserver-initiated requests, so it costs nothing. `restart_test.py` proves both\nbehaviours.\n\nThe bearer token is the only authentication on that port, so anything that can\nreach it inherits this server's TRMM permissions. Keep it on the LAN or behind a\ntunnel rather than binding a public interface.\n\n## Connecting a client\n\nYou need two things from the server: the **bearer token** from `.env`, and a\ncopy of **`certs/cert.pem`** so the client can verify the TLS certificate.\n\nClaude Code speaks HTTP directly and needs no bridge:\n\n```bash\nclaude mcp add --transport http trmm https://192.0.2.10:8770/mcp \\\n  --header \"Authorization: Bearer <TRMM_MCP_AUTH_TOKEN>\" --scope user\n```\n\nOn the server itself you can skip the network entirely and run it over stdio:\n\n```bash\nclaude mcp add trmm -- /opt/trmm-mcp/run.sh readonly\n```\n\nSwap `readonly` for `elevate` to get the approval gate, or `command` for\nunattended execution.\n\nClaude Desktop needs the `mcp-remote` bridge, LM Studio speaks remote HTTP\nnatively, and either can instead be run across SSH with nothing listening on the\nnetwork at all. Working configs for all three on macOS, Windows and Linux — plus\ninstalling the certificate into the system trust store — are in\n**[docs/clients.md][clients]**.\n\n## Tools\n\n**28 tools: 20 read-only, 8 execution.** Anywhere a tool takes an agent you can\npass **the hostname or the agent_id** — hostnames are resolved automatically,\nand an ambiguous one is rejected rather than guessed.\n\n- **Start here** — `trmm_fleet_overview`: counts, plus the offline,\n  needs-reboot, failing-check and pending-patch lists.\n- **Fleet** — agents with status and filters, clients and sites, alerts,\n  pending actions, server info and the active mode.\n- **Diagnostics** — services, processes, event log, configured checks,\n  installed software, patch status, automated tasks, and past command and\n  script runs *with their output*.\n- **Audit and scripts** — the TRMM audit log, the server debug log, the script\n  library and full script source.\n- **Escape hatch** — `trmm_api_get`: a raw GET against any API path.\n- **Execution** (`elevate` and `command` only) — run a command, run a saved\n  script, reboot, start/stop/restart a service, kill a process, wake-on-LAN,\n  force checks to run, run an automated task.\n\nBulk fleet-wide execution, server-side scripts and all config mutation are\ndeliberately **not** exposed. The full 28-row table, the reasoning behind the\nomissions, the MCP safety annotations and the context-size handling are in\n**[docs/tools.md][tools]**.\n\n## Documentation\n\n| | |\n|---|---|\n| **[Security][security]** | The approval gate, the three read-only layers, TLS, and the honest caveats |\n| **[Installation][installation]** | pip versus a clone, where it keeps its files, rebuilding the venv |\n| **[Connecting a client][clients]** | Claude Code, Claude Desktop, LM Studio, SSH, and the certificate |\n| **[Tools][tools]** | All 28 tools, what is not exposed, annotations, context-size handling |\n| **[Operations][operations]** | Audit logging, the browser log pages, backups, testing, troubleshooting |\n| **[Configuration][configuration]** | Every environment variable, and what each file in the repo does |\n| **[TRMM API][trmm-api]** | Independent documentation of the TacticalRMM API itself |\n\n## Changelog\n\nSee [CHANGELOG.md][changelog].\n\n## License\n\nAGPL-3.0-or-later (`LICENSE`), with per-file SPDX headers. The copyleft terms\nmean anyone who runs a modified copy as a network service must publish their\nchanges — deliberate, to keep execution-capable forks open.\n\n[security]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/security.md\n[installation]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/installation.md\n[clients]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/clients.md\n[tools]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/tools.md\n[operations]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/operations.md\n[configuration]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/configuration.md\n[trmm-api]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/trmm-api.md\n[audit-log]: https://github.com/shin2344234/trmm-mcp/blob/master/docs/operations.md#audit-logging\n[changelog]: https://github.com/shin2344234/trmm-mcp/blob/master/CHANGELOG.md\n",
  "bytes": 11577,
  "sha": "c50965b8e334358fae7f3df3579ce9489e374d95d536dd4736890d5a81a7cd5a",
  "repo_slug": "shin2344234/trmm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shin2344234_trmm_mcp_09f8553e/readme"
}