Woow Podman MCP Server

Woow Podman MCP Server

A FastMCP server that exposes a Podman host through its libpod REST API as MCP tools, plus aweb admin console that supervises it, gates it, and publishes it on an authenticated URL thatClaude (or any MCP client) can connect to directly.

Three components, one container:

The connector URL is https://<host>/private_<mcp_auth_token>/mcp/. The path segment is thecredential — see Security.

Quick start

git clone https://github.com/WOOWTECH/Woow_podman__mcp_server.git
cd Woow_podman__mcp_server

# Podman's rootless socket must be running.
systemctl --user enable --now podman.socket

PODMAN_SOCK=/run/user/$(id -u)/podman/podman.sock \
PODMAN_UID=$(id -u) PODMAN_GID=$(id -g) \
JWT_SECRET=$(openssl rand -hex 32) \
docker compose up --build

Then:

1. Open http://localhost:8080. The admin password is printed once in the first-boot logs(ADMIN_PASSWORD not set — generated one for first boot: …), or set ADMIN_PASSWORD yourself.
2. Tokens → Rotate to mint the MCP auth token. It is shown once.
3. Point your client at http://localhost:8080/private_<that token>/mcp/.

To skip the GUI entirely, seed the config file directly:

python3 scripts/seed.py --config ./data/config.json --profile safe

Safety profiles

Tools are gated at registration time, not at list time. A tool outside the active profile doesnot exist on the protocol — it cannot be called by name, cannot be reached by a client that cachedan older tools/list, and does not appear in the schema. This is deliberate: a gate that onlyfilters the listing is bypassed by any client that already knows the tool name.

Set with PODMAN_MCP_PROFILE. In Kubernetes the profile lives in the Secret, so changing itrequires a rollout — the GUI deliberately cannot widen it.

Security

The Podman socket is the entire boundary. Anything that can reach it can start a privilegedcontainer and therefore own the host account. Three rules:

1. Mount the rootless socket (/run/user/<uid>/podman/podman.sock), never the root service's.
2. Run the container as that same uid/gid. A bind mount the process cannot connect to fails withEACCES, which reads like a bug rather than a permission problem.
3. Leave the profile at safe unless you specifically need the destructive tools.

No OAuth. The server answers every /.well-known/* probe and /register with a JSON 404.This is not an omission — it is the fix. The SPA catch-all used to answer those probes with200 text/html, which a client reads as "yes, I have an authorization server"; it then attemptedDynamic Client Registration, got HTML back, and failed with "Couldn't register with … 's sign-inservice" in a redirect loop. A clean 404 makes discovery fail fast so the client falls back toanonymous access and just sends initialize.

The path token is the credential. It is compared with secrets.compare_digest, never echoedback unmasked, and rotating it from the Tokens page restarts the child. Put the console behind atunnel with TLS; do not expose :8080 directly.

Configuration

Everything lives in /data/config.json (MCP_ADMIN_CONFIG), written atomically and chmod 600.The connection section is upper-cased into the child's environment, so podman_uri arrives asPODMAN_URI.

See .env.example for the full list. The ones that matter:

Notes from the field

• podman stats with an unknown name. libpod answers HTTP 200 with{"Error": {}, "Stats": null} — and {} is falsy, so the obvious if payload.get("Error") checknever fires and the tool silently returns nothing. It also returns no stats when anyrequested name is unknown, not just the bad one, so the error names the whole batch rather thanaccusing a container that is running fine.
• podman top with plain ps flags. libpod returns fewer columns than titles for flag-styleargs like aux, so the rows cannot be tabulated. The tool detects the mismatch and prints the rawoutput with a hint to use descriptor form (ps_args="-eo pid,user,comm") instead of producing acolumn-shifted table.
• Stream framing. libpod is always 8-byte multiplexed, even with a TTY; only the Docker-compat/v1.x endpoints go raw. The tty flag is passed down explicitly rather than guessed from thepayload, because output that happens to start with \x01\x00\x00\x00 is otherwise eaten.

Development

pip install -e ".[dev]"
pytest                      # 22 tests, no network, no Podman required
cd frontend && npm install && npm run dev

Run the console against a local Podman without Docker:

python3 scripts/seed.py --config /tmp/pm/config.json \
    --podman-uri unix:///run/user/$(id -u)/podman/podman.sock
MCP_ADMIN_CONFIG=/tmp/pm/config.json JWT_SECRET=dev \
    uvicorn podman_mcp_admin.main:app --port 8080

Or run the MCP server on its own, with no console at all:

PODMAN_MCP_PROFILE=readonly python3 -m woow_podman_mcp_server.server   # stdio

Roadmap

Phase 1 (this release) is "the console comes up and the connector works". The MCP server is asingle self-contained server.py; the console supervises it, proxies it, streams its logs androtates its token.

Until Phase 2/3 land, the Connection and Tools pages get a JSON 404 from the API fallbackand render empty. That is intentional and easier to debug than a stub that pretends to work.

License

MIT — see LICENSE.