面向 Podman 和 Docker 的 MCP Server，让 AI 助手通过自然语言管理容器生命周期。
定位#
Podman MCP Server 是一个基于 Model Context Protocol 的容器管理服务，由 Marc Nuri (manusa) 以 Go 语言开发并维护。项目同时兼容 Podman 和 Docker 两种容器运行时，支持 STDIO 与 HTTP（Streamable HTTP + SSE）两种传输模式。
核心能力#
双容器运行时支持#
同时兼容 Podman 和 Docker，后端采用智能检测机制：优先通过 Unix Socket 调用 Podman REST API（优先级 100），不可用时回退至 CLI 命令调用（优先级 50），也可通过 --podman-impl 参数强制指定。
传输模式#
- STDIO（默认）：标准输入/输出通信，适用于 Claude Desktop 等本地客户端
- HTTP（
--port）：同时暴露 Streamable HTTP (/mcp) 和 SSE (/sse) 端点 - SSE-only（已废弃）：旧版模式，建议迁移至
--port
MCP 工具集（12 个）#
| 类别 | 工具 | 能力 |
|---|---|---|
| Container | container_run | 运行容器（支持环境变量、端口映射） |
| Container | container_list | 列出运行中的容器 |
| Container | container_inspect | 查看容器低级别信息与配置 |
| Container | container_logs | 查看容器日志 |
| Container | container_stop | 停止运行中的容器 |
| Container | container_remove | 移除容器 |
| Image | image_build | 从 Dockerfile/Podmanfile/Containerfile 构建镜像 |
| Image | image_list | 列出本地镜像 |
| Image | image_pull | 从 Registry 拉取镜像 |
| Image | image_push | 推送镜像到 Registry |
| Image | image_remove | 删除本地镜像 |
| Network | network_list | 列出可用网络 |
| Volume | volume_list | 列出可用卷 |
多客户端适配#
已适配 Claude Desktop、Claude Code CLI、VS Code / Cursor、Goose CLI 等主流 AI 客户端。
架构要点#
- 核心语言为 Go（94.2%），采用标准 Go 项目布局（
cmd/、pkg/、internal/） - API 通信层（
pkg/bindings）通过 Unix Socket 与 Podman REST API 通信，为首选路径 - CLI 回退层在 REST API 不可用时通过调用
podman/docker命令行实现同等功能 - npm 分发包装脚本位于
npm/podman-mcp-server/bin/，使 Go 二进制可通过npx调用 - Python 相关内容位于
python/目录，同步发布至 PyPI（具体功能范围待确认） - 支持使用
@modelcontextprotocol/inspector进行 MCP Server 调试 - CI/CD 通过 GitHub Actions（
build.yamlworkflow）实现 - MCP 名称注册为
io.github.manusa/podman-mcp-server
安装与配置#
前置条件：安装 Podman 或 Docker 并确保运行时可访问。
方式一：npx（推荐）
npx podman-mcp-server@latest --help
方式二：二进制下载 从 GitHub Releases 下载对应平台二进制文件。
方式三：pip
pip install podman-mcp-server
Claude Desktop 配置（claude_desktop_config.json）：
{
"mcpServers": {
"podman": {
"command": "npx",
"args": ["-y", "podman-mcp-server@latest"]
}
}
}
VS Code 配置：
code --add-mcp '{"name":"podman","command":"npx","args":["-y","podman-mcp-server@latest"]}'
关键 CLI 选项#
| 选项 | 描述 |
|---|---|
--port, -p | 以 HTTP 模式启动（同时暴露 Streamable HTTP + SSE） |
--output-format, -o | 列表命令输出格式：text（默认）或 json |
--podman-impl | 强制指定后端实现：api 或 cli（默认自动检测） |
--sse-port | ⚠️ 已废弃，请使用 --port |
能力边界与注意事项#
- 不支持容器编排（如 Podman Compose / Docker Compose）等高级编排能力
- 当前最新 release 为 v0.0.15，处于 0.0.x 早期开发阶段，Tool 签名与行为可能尚未稳定，存在 Breaking Change 风险
- HTTP 模式下的认证机制、多用户隔离等安全考量在文档中未提及
- 采用 Apache-2.0 许可证