Docker MCP Toolkit & Gateway (Official)

什么是 Docker MCP Toolkit & Gateway (Official)？

Docker MCP Toolkit & Gateway (Official) 是 Docker 官方的 docker mcp 方案：由 docker mcp CLI 插件和 MCP Gateway 组成，把 Docker MCP Catalog 中的 MCP 服务器作为隔离容器运行，并通过同一个端点提供给 Claude、Cursor、VS Code 等客户端。

开源仓库 docker/mcp-gateway（MIT 许可）包含支撑 MCP Toolkit 的 CLI 插件。MCP Catalog（hub.docker.com/mcp，OCI 镜像 mcp/docker-mcp-catalog）列出容器化的服务器，MCP Gateway 负责运行它们并路由调用，MCP Toolkit 则是构建在两者之上的 Docker Desktop 界面。

如何使用 Docker MCP Toolkit & Gateway (Official)？

前提条件：已启用 MCP Toolkit 的 Docker Desktop（Settings → Beta features → Enable Docker MCP Toolkit → Apply）。Docker 文档描述的是 Docker Desktop 4.62 及以上版本的界面和 docker mcp 命令。

在 Docker CE、WSL2 或容器中，README 要求先运行：

export DOCKER_MCP_IN_CONTAINER=1
docker mcp feature enable profiles

1. 从目录中挑选服务器

docker mcp catalog pull mcp/docker-mcp-catalog
docker mcp catalog server ls mcp/docker-mcp-catalog

输出的名称（如 github-official）就是 catalog:// 引用中使用的 ID。

2. 创建 profile（客户端所连接的一组具名服务器）：

docker mcp profile create --name web-dev
docker mcp profile server add web-dev \
  --server catalog://mcp/docker-mcp-catalog/github-official \
  --server catalog://mcp/docker-mcp-catalog/playwright

3. 运行网关

docker mcp gateway run --profile web-dev

不带 --profile 时使用名为 default 的 profile。通常由客户端通过 stdio 自行启动该命令。

4. 连接客户端。 docker mcp client connect 支持的名称包括 claude-code、claude-desktop、cursor、vscode、codex、gemini、zed、cline、continue、goose、kiro、lmstudio 和 opencode。

docker mcp client ls
docker mcp client connect <client> --profile web-dev

Claude Code

docker mcp client connect claude-code --profile web-dev --global

之后运行 claude mcp list，应能看到 MCP_DOCKER 显示为已连接。

Claude Desktop

在 Docker Desktop 中打开 MCP Toolkit → Clients，点击 Claude Desktop 旁的 Connect，然后重启 Claude Desktop。Docker 文档给出的手动配置：

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"]
    }
  }
}

Cursor

docker mcp client connect cursor --profile web-dev

在 Cursor Settings → Tools & MCP 中确认出现 MCP_DOCKER。

VS Code

在项目目录中运行（会生成一个用户专属的 .vscode/mcp.json）：

docker mcp client connect vscode --profile web-dev
echo ".vscode/mcp.json" >> .gitignore

Codex

docker mcp client connect codex --profile web-dev
codex mcp list

MCP_DOCKER 应显示为 “enabled” 状态。

Docker MCP Toolkit & Gateway (Official) 的主要功能

• Docker 官方项目，MIT 许可，随 Docker Desktop 提供，也可独立使用
• 每个服务器运行在独立容器中，默认限制为 1 个 CPU 和 2 GB 内存，未经授权无法访问宿主机文件系统
• Docker MCP Catalog 中 mcp/ 下的镜像由 Docker 构建并签名，附带 SBOM，默认进行签名校验
• 密钥来自 Docker Desktop 的密钥存储（操作系统钥匙串），而不是客户端环境变量，并且只对声明它的服务器可见
• 内置 OAuth 流程，适用于 GitHub、Notion、Linear 等服务器
• profile 支持按服务器配置和工具白名单，可通过 OCI 仓库或导出文件共享
• 默认使用 stdio，另支持受 bearer token 保护的 sse 和 streaming HTTP 传输
• 同时发布为 docker/mcp-gateway 镜像，可用于 Docker Compose 和 CI

Docker MCP Toolkit & Gateway (Official) 工具

网关会暴露 profile 中每个服务器的工具。在此之上，Dynamic MCP（标注为实验性）还增加了几个管理工具：

• 发现： mcp-find 按名称或描述搜索目录。
• 会话管理： mcp-add 和 mcp-remove 为当前会话添加或移除服务器，mcp-config-set 用于配置服务器。以这种方式添加的服务器不会保存到 profile。
• 执行： mcp-exec 按名称运行工具，code-mode 将多个服务器的工具组合成一个 JavaScript 工具；Docker 表示 code mode 目前还不适合常规使用。

如果需要固定的工具列表，可用 docker mcp feature disable dynamic-tools 关闭这些工具。要精简 profile 内的工具，使用白名单：

docker mcp profile tools web-dev --disable-all github-official
docker mcp profile tools web-dev --enable github-official.list_issues

Docker MCP Toolkit & Gateway (Official) 的使用场景

• 在隔离容器中运行社区 MCP 服务器，而不是在宿主机上直接用 npx 或 uvx 运行。
• 让智能体按需寻找工具：“What MCP servers can I use for working with SQL databases?”，然后 “Add the postgres mcp server.”
• 在 Docker Compose 或 CI 中通过 --servers 为智能体提供网关，无需 Docker Desktop。
• 将智能体限制在公司目录内：docker mcp gateway run --catalog <oci-reference>。

Docker MCP Toolkit & Gateway (Official) 与替代方案对比

“docker mcp” 这个说法也包括用来管理 Docker 本身的服务器，这是另一类用途。mcp-server-docker（ckreiling，社区项目）用自然语言管理 Docker：编排容器、调试运行中的容器以及管理数据卷；docker-mcp（QuantGeekDev，社区项目）可以创建容器、部署 Compose 栈并读取容器日志。想要控制 Docker，请用这些服务器；想要为客户端运行并保护大量 MCP 服务器，请用官方的 Docker MCP Toolkit。完整步骤见我们的 Docker MCP Gateway 配置指南。

Docker MCP Toolkit & Gateway (Official) 常见问题排查

• 客户端看不到任何工具： 运行 docker mcp gateway run --verbose --dry-run。它会打印已启用的服务器、已拉取的镜像和工具数量，可发现服务器名称错误、配置或密钥缺失等问题。
• 单独测试一个工具： 使用 docker mcp tools call <tool-name> [arguments...] 并加上 --verbose。
• 守护进程在运行却提示 “Docker Desktop is not running”： 执行 export DOCKER_MCP_IN_CONTAINER=1（适用于 WSL2、Docker CE、容器环境）。
• 出现 “unsupported dialect” 模式错误： 更新网关；当前版本会把 draft-04/06/07 工具模式转换为 JSON Schema 2020-12。
• 教程步骤与界面不符： Docker 文档针对 Docker Desktop 4.62+；更早的版本使用不同的 Toolkit 界面。