mcp-podman-crunchtools
# mcp-podman-crunchtools
<!-- mcp-name: io.github.crunchtools/podman -->
MCP server for Podman container management via the Podman REST API. Manages containers, images, pods, networks, volumes, and system info. Supports both rootful and rootless Podman.
## Installation
```bash
# uvx (zero-install)
uvx mcp-podman-crunchtools
# pip
pip install mcp-podman-crunchtools
# Container
podman run -v /run/podman/podman.sock:/run/podman/podman.sock:z \
--security-opt label=type:container_runtime_t \
quay.io/crunchtools/mcp-podman
```
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PODMAN_SOCKET` | No | Auto-detect | Unix socket path |
| `PODMAN_SOCKET_FILE` | No | — | File containing socket path |
| `PODMAN_TIMEOUT` | No | 30 | Request timeout in seconds |
Socket auto-detection order:
1. `$XDG_RUNTIME_DIR/podman/podman.sock` (rootless)
2. `/run/user/$UID/podman/podman.sock` (rootless fallback)
3. `/run/podman/podman.sock` (rootful)
## Claude Code Integration
```bash
claude mcp add mcp-podman-crunchtools \
--env PODMAN_SOCKET=/run/podman/podman.sock \
-- uvx mcp-podman-crunchtools
```
## Tools (30)
### Containers (12)
| Tool | Description |
|------|-------------|
| `container_list` | List containers |
| `container_inspect` | Get container details; environment values are redacted, names kept |
| `container_start` | Start a container |
| `container_stop` | Stop a container |
| `container_restart` | Restart a container |
| `container_kill` | Send signal to container |
| `container_rm` | Remove a container |
| `container_logs` | Get container logs |
| `container_top` | List processes |
| `container_stats` | Resource usage |
| `container_create` | Create a container |
| `container_prune` | Remove stopped containers |
### Images (5)
| Tool | Description |
|------|-------------|
| `image_list` | List images |
| `image_inspect` | Get image details |
| `image_pull` | Pull from registry |
| `image_rm` | Remove an image |
| `image_prune` | Remove unused images, with the options of `podman image prune` (`all`, `external`, `build_cache`, `filters`) |
### Pods (7)
| Tool | Description |
|------|-------------|
| `pod_list` | List pods |
| `pod_inspect` | Get pod details |
| `pod_start` | Start a pod |
| `pod_stop` | Stop a pod |
| `pod_restart` | Restart a pod |
| `pod_rm` | Remove a pod |
| `pod_create` | Create a pod |
### Networks (2)
| Tool | Description |
|------|-------------|
| `network_list` | List networks |
| `network_inspect` | Get network details |
### Volumes (2)
| Tool | Description |
|------|-------------|
| `volume_list` | List volumes |
| `volume_inspect` | Get volume details |
### System (2)
| Tool | Description |
|------|-------------|
| `system_info` | Podman system info |
| `system_df` | Disk usage |
## License
AGPL-3.0-or-later
TDQS
Scored across 30 tools
Each tool targets a distinct resource+action pair (container_start vs container_stop vs container_kill), and the resource prefix separates container/image/pod/network/volume tools cleanly. Minor potential confusion between container_kill and container_stop, and between prune vs rm, but descriptions clarify these.
Every tool follows the same resource_action_tool pattern (container_list_tool, image_pull_tool, pod_restart_tool), making the surface highly predictable. No mixed conventions.
30 tools is above the comfortable band, but the breadth is justified by six distinct resource domains (container, image, pod, network, volume, system). Each tool earns its place, though the set feels heavy for a single server.
Containers, images, and pods have solid lifecycle coverage (list/inspect/create/start/stop/restart/rm/prune). However, networks and volumes only have list/inspect with no create/rm, and container exec, image build/push, and container run are missing, leaving notable gaps.