containerport

containerport

containerport 是一款小巧的 MCP 服务和 CLI，用于日常 Docker 容器操作。它以干净室方式重建了一组明确限定的核心容器操作——十个直接对应 Docker CLI 的工具：列出、检查、运行、启动、停止和移除容器，列出和拉取镜像，读取容器日志，以及列出卷。

它刻意不做 Docker 的 MCP 目录／工具包网关。不支持 compose、构建镜像、网络或 swarm 管理、注册表身份验证、进入容器执行命令，也不提供目录／网关工具——只有 Agent 最常用的容器操作，并且都通过主机的 docker 二进制文件如实执行。

每次调用都会构建为参数数组，并按 execFile 语义运行——绝不使用 shell 字符串——因此镜像名称、环境变量值和端口不会被重新解释为 shell 语法。传给 run-container 的 command 会通过容器自身的 sh -c 运行，而非主机 shell。执行器可注入，测试套件正是通过注入假执行器来验证确切的参数数组。

主机需要可正常工作的 docker CLI。如果缺少 docker，调用会如实返回底层的启动错误（ENOENT），而非伪造结果。发布的容器镜像不包含 docker 二进制文件：它需要主机执行器（例如挂载 Docker 套接字的工作流），并在 Dockerfile 中说明了这一点。

安装

npx @reneturcios/containerport list-containers --all
docker run -i ghcr.io/cloudcorprecords/containerport

CLI

containerport list-containers [--all]
containerport inspect-container <container_id>
containerport run-container <image> [--name n] [--port 8080:80] [--env KEY=val] [--command "echo hi"]
containerport start-container <container_id>
containerport stop-container <container_id>
containerport remove-container <container_id> [--force]
containerport list-images
containerport pull-image <image>
containerport get-container-logs <container_id> [--tail 100]
containerport list-volumes
containerport --version

退出代码：0 表示成功，1 表示 docker 错误，2 表示用法错误。

MCP 服务

npx -y @reneturcios/containerport mcp

{
  "mcpServers": {
    "containerport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/containerport", "mcp"]
    }
  }
}

工具

工具	输入	功能
list_containers	all（布尔值，可选）	执行 docker ps [--all] --format json 并解析结果。
inspect_container	container_id（必填）	执行 docker inspect，返回单个文档。
run_container	image（必填）、name、ports[]、env[]、command	执行 docker run -d，返回新容器 ID。
start_container	container_id（必填）	执行 docker start。
stop_container	container_id（必填）	执行 docker stop。
remove_container	container_id（必填）、force	执行 docker rm [-f]。
list_images	—	执行 docker images --format json 并解析结果。
pull_image	image（必填）	执行 docker pull。
get_container_logs	container_id（必填）、tail	执行 docker logs [--tail n]。
list_volumes	—	执行 docker volume ls，解析驱动／名称对。

执行器错误——缺少 docker 二进制文件、守护进程错误、容器不存在——都会作为工具错误返回，并附带底层错误消息。

开发

npm install
npm run build
npm test
npm run dev

测试完全使用假执行器运行：验证确切的参数数组、输出解析和错误传递。不会连接真实的 Docker 守护进程。

许可证

MIT — 详见 LICENSE。