My ZimaBlade runs 16 containers: Immich, a dashboard, Uptime Kuma, a reverse proxy and a few others. When something feels slow, the question is always the same one: is the box busy, and which container is it? I got fed up SSHing in to run docker stats, so my self-hosted agent has had a set of "Zima ops" tools for a while. Today I cleaned them up and published them as zima-mcp.

zima-mcp running against my real ZimaBlade: tool list, load average, per-container stats and a refused restart

What it is

An MCP server. MCP is the plug that lets Claude Desktop, Claude Code, Cursor and other AI clients call tools. zima-mcp gives them seven:

  • zima_load: uptime and load average
  • zima_top: top processes by CPU
  • zima_docker_ps and zima_docker_stats: containers, and CPU/memory per container
  • zima_disk: df -h
  • zima_container_logs: the last N lines for one container
  • zima_restart_container: restart one container, only if it's on your allowlist

Every tool is one fixed command over plain SSH. Nothing gets installed on the Zima.

The bit I actually care about: what it can't do

ZimaOS is a bit odd. The normal user can run docker without sudo, because it's in the docker group, but sudo itself wants a password. I leaned into that rather than fighting it. The agent gets no sudo, no reboot, and no killing root processes. There are no tools for those, and there's a test that checks none of the commands contain them.

Restarts are opt-in per container. I let it bounce the Immich containers, because those are what actually fall over. I don't let it touch the reverse proxy, the login service or the tunnel. Restarting those at the wrong moment locks me out, and an agent being helpful at 2am is exactly when that happens.

What I found tidying it up

The old version quoted the container name before sending it over SSH, so a;reboot was already harmless. But quoting doesn't stop a name like --help or -f. Docker reads that as a flag, not a container. Nothing bad came of it, but it's the kind of thing you only spot when you write tests for someone else's box. Container names are now checked against Docker's own naming rules (letters, digits, _ . -, no leading dash) before they go anywhere near a shell.

Proving the setup guide works

Every one of my repos is getting a setup guide, and I'm sick of guides that were right once. This one is tested. On every change, a GitHub runner plays both parts: it's the computer running the AI client, and it's the "Zima" (SSH to localhost, real Docker, a real nginx container). It installs zima-mcp the way the guide says, calls every tool, restarts an allowlisted container, checks a non-allowlisted one is refused, and talks to the server over real MCP stdio. If the guide goes stale, the check goes red.

What CI can't prove is the ZimaOS-specific bit and your client's config file. The guide says so rather than pretending.

Try it

pipx install git+https://github.com/casareanderson/zima-mcp ZIMA_HOST=your-zima ZIMA_USER=you zima-mcp --call zima_load claude mcp add zima -e ZIMA_HOST=your-zima -e ZIMA_USER=you -- zima-mcp 

It works on any Linux box where your user can run Docker, not just a Zima. It's free and MIT: github.com/casareanderson/zima-mcp. The full walkthrough, with Claude Desktop, Cursor and the common errors, is in docs/SETUP.md.

Would you let an agent restart containers on your server? And which ones would you never put on the list?

🤖 Drafted with AI assistance from my own homelab notes, logs and repos, then reviewed and edited before publishing.