Woow Podman MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| JWT_SECRET | No | Secret used for JWT signing and session validation. If not set, a random one is generated per process. | |
| PODMAN_URI | No | The URI for the Podman socket (e.g., unix:///run/podman/podman.sock or tcp://host:2376). | unix:///run/podman/podman.sock |
| ADMIN_PASSWORD | No | Password for the admin console. If not set, a random password is generated and logged on first boot. | |
| MCP_ADMIN_CONFIG | No | Path to the configuration file where settings such as the connection and profile are stored. | /data/config.json |
| PODMAN_API_VERSION | No | The libpod API version to target. Must not be newer than the daemon's version. | v5.0.0 |
| PODMAN_MCP_PROFILE | No | The safety profile: readonly, safe, or full. Controls which MCP tools are exposed. | safe |
| PODMAN_MCP_MAX_CHARS | No | Maximum number of characters per tool response. Tools truncate by row and report dropped rows. | 20000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Manage a Podman host through its libpod REST API. Active safety profile: safe. Prefer podman_ps / podman_container_logs before acting. Container inspect output is large — use podman_ps first and inspect one target.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| podman_infoA | Podman host 概況:版本、OS、runtime、rootless、資源用量。 |
| podman_psA | 列出 containers。預設只列 running,all=true 含已停止。 |
| podman_container_inspectA | Inspect 單一 container 的完整設定/狀態。輸出很大,只查你要的那一個。 |
| podman_container_logsA | 取 container logs。預設只取最後 200 行;stderr 行會以 'E| ' 前綴標示。 |
| podman_container_statsB | container 即時資源用量(單次快照,不 streaming)。 |
| podman_container_topA | 列出 container 內的 process (podman top)。 |
| podman_container_healthcheckB | 執行並回報 container 的 healthcheck 結果。 |
| podman_imagesB | 列出本機 images。 |
| podman_podsB | 列出 pods 與其中的 containers。 |
| podman_volumesA | 列出 volumes。 |
| podman_networksC | 列出 networks。 |
| podman_system_dfB | 磁碟用量統計 (podman system df)。 |
| podman_eventsA | 讀取 podman 事件流(有界,不會卡住)。查故障時間線很好用。 |
| podman_container_startC | 啟動 container。 |
| podman_container_stopA | 停止 container(預設 10 秒後 SIGKILL)。 |
| podman_container_restartC | 重啟 container。 |
| podman_container_execA | 在既有 container 內執行指令,回傳 stdout/stderr 與 exit code。 stderr 行會以 'E| ' 前綴標示(tty=true 時為 raw、無前綴)。 |
| podman_image_pullA | 從 registry 拉 image。會等到拉完,大 image 請留意 timeout。 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 18 tools
Every tool has a clearly distinct purpose: listing containers, inspecting, starting, stopping, logs, stats, top, healthcheck, exec, plus separate tools for images, pods, volumes, networks, and host-level info. There is no overlap that would cause an agent to misselect.
The tools consistently use the podman_ prefix and snake_case throughout. Most container operations follow a resource_action pattern (podman_container_start), while some are noun-only (podman_ps, podman_images, podman_events) or compound (podman_system_df), mirroring the podman CLI. The minor style variation is acceptable but not perfectly uniform.
With 18 tools, the server is slightly above the typical well-scoped range of 3-15. However, the breadth of Podman features covered (containers, images, pods, volumes, networks, events, exec) justifies the count, and each tool adds value without redundancy.
The tool set is largely read-oriented and lacks fundamental lifecycle operations. There is no way to create or delete containers, pods, volumes, networks, or images (except pulling). Starting/stopping/restarting and exec provide some control, but the missing CRUD operations are significant gaps for a general Podman server.