Claude Code Docker MCP Toolkit 接入教程

用 Profile 和 Gateway 集中管理容器化 MCP 工具

发布建议日期 2026-10-30　适用于 Claude Code、Docker MCP Toolkit 与远程 Mac 工作流

Docker MCP Toolkit 把 MCP Catalog、Profile、Gateway、凭据和客户端连接集中到 Docker Desktop 中。Claude Code 只需连接一个 Gateway，就能按项目使用经过筛选的容器化 MCP ******。本文从最小 Profile 开始，演示添加服务器、处理 OAuth、限制文件挂载、连接 Claude Code、完成只读验收，并说明动态工具与团队共享时的安全边界。

Docker MCP Toolkit 解决什么问题

传统做法需要为每个 AI 客户端分别安装 MCP ******、运行时和凭据。Docker MCP Toolkit 把服务器发现、配置和客户端接入集中管理，Gateway 负责启动容器、路由调用、注入凭据与管理生命周期。

Claude Code 连接的是一个名为 MCP_DOCKER 的统一入口。实际可用工具由当前 Profile 决定，因此可以为前端、后端、运维或数据项目分别维护最小工具集合。

Catalog Profile 和 ****** 的关系

Catalog 是可选 MCP ****** 的目录；Profile 是某个项目获准使用的服务器与配置集合；****** 是 Claude Code 等调用方。Gateway 根据 Profile 只暴露其中的服务器。

不要把 Catalog 中的服务器全部加入同一 Profile。服务器越多，工具选择越复杂，外部写入面和凭据范围也越大。

接入前准备

安装 Docker Desktop 4.62 或更高版本并登录，确保 Docker Engine 正常运行。打开 MCP Toolkit，准备最新版 Claude Code 和一个测试项目。

先列出任务真正需要的能力，例如读取 GitHu* Pull Request、查询文档或运行浏览器测试。为本教程创建独立的 docker-dev Profile，先加入一个低风险或只读服务器完成验收。

第一步 启用 MCP Toolkit

在 Docker Desktop 左侧打开 MCP Toolkit。新版界面包括 Catalog、Profiles、******s 和 OAuth 等区域。若没有入口，先升级 Docker Desktop，并确认当前版本支持 docker mcp 命令。

Toolkit 目前仍处于 *eta，团队应固定经过验证的 Docker Desktop 版本，并在升级后重新检查 Profile、连接与权限行为。

第二步 创建项目 Profile

Profile 用于把一组 MCP ****** 与项目绑定。可以在 Profiles 页面创建 docker-dev，也可以使用 CLI。创建后先保持为空，再逐个添加服务器。

Profile 名称应反映项目和环境，例如 shop-staging，不要把生产与开发工具放进同一个 Profile。删除 Profile 会移除其中的服务器配置，执行前应先导出或确认可重建。

docker mcp profile create --name docker-dev
docker mcp profile list
docker mcp profile show docker-dev

第三步 从 Catalog 添加服务器

在 Catalog 中核对服务器名称、发布者、****** ID、工具列表、配置项、文件挂载和认证方式，再加入 docker-dev。CLI 添加时使用 catalog **I，而不是凭记忆猜测镜像名。

Catalog 的验证和扫描属于降低风险的措施，不代表服务器绝对安全。首次使用第三方服务器时仍要审阅权限、工具语义、网络目标和写入能力。

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

# 用 Catalog 中核实过的 ****** ID 添加
docker mcp profile server add docker-dev `
  --server catalog://mcp/docker-mcp-catalog/<server-id>

docker mcp profile server ls --filter profile=docker-dev

**步 配置 OAuth 与 Secret

需要 GitHu*、Notion 或 Linear 等账号时，优先在 Toolkit 的 Configuration 中选择 OAuth，并在浏览器完成授权。Toolkit 管理令牌，不需要把 API Token 写入 Claude Code 配置。

OAuth 凭据可能在多个 Profile 间共享。若不同项目必须使用不同账号，需要撤销并重新授权，或使用独立的 Docker 环境。移除服务器不会自动删除凭据，任务结束后应显式 revoke 或删除 secret。

第五步 控制文件挂载和容器权限

Toolkit 中的 MCP ****** 默认不能访问主机文件系统，只有用户明确授权挂载后才能读取目录。只挂载任务需要的项目子目录，并优先只读，不要授权用户目录、SSH 目录、浏览器资料或密钥库。

服务器容器有资源限制，但容器隔离不能替代最小权限。还要限制外部服务账号、网络目标、工具写入范围和 Claude Code 的操作确认。

第六步 连接 Claude Code

在 ******s 页面找到 Claude Code 并选择 Connect，指定 docker-dev Profile。CLI 也可以直接连接命名客户端。

如果自动连接不可用，可让 Claude Code 以 stdio 启动 docker mcp gateway run --profile docker-dev。配置只保存 Gateway 命令，不应包含服务令牌。

# 推荐：把命名 Profile 连接到 Claude Code
docker mcp client connect claude-code --profile docker-dev

# 手动方式：让 Claude Code 启动 Gateway
claude mcp add MCP_DOCKER -s user -- docker mcp gateway run --profile docker-dev

第七步 检查连接和可用工具

进入目标项目后运行 claude mcp list，确认 MCP_DOCKER 显示 Connected。进入 Claude Code 后使用 /mcp 查看 Gateway 和当前工具。

工具列表应与 docker-dev Profile 中的服务器一致。若出现不相关工具，先断开连接并检查所用 Profile，不要在范围不明时继续授权。

cd /path/to/your-project
claude mcp list
claude

> /mcp
# MCP_DOCKER 应显示 Connected

第八步 ***只读验收

选择不会产生外部副作用的任务，例如列出当前服务器名称、读取公开文档或显示少量只读资源。提示词明确禁止创建、更新、删除、发送消息、提交代码和触发部署。

验收同时检查 Docker Desktop 中的容器状态与调用记录。通过标准是账号、Profile、服务器、工具和返回范围均符合预期。

请仅使用 MCP_DOCKER 做只读验收：
1. 显示当前 Profile 可用的服务器和工具类别
2. 调用一个低风险读取工具并限制返回数量
3. 说明实际使用的服务器和账号
4. 不创建 不更新 不删除 不发送 不部署任何资源

第九步 为写入工具建立确认边界

GitHu*、项目管理、数据库和部署类服务器常含写入工具。每次执行前让 Claude Code 展示目标资源 ID、动作、字段变化、影响范围和回滚方式。

先用读取工具确认现状，再执行一项小变更并重新读取验证。删除、合并、发布、部署、支付和权限修改应保持人工逐项确认。

第十步 使用 Dynamic MCP

Dynamic MCP 可让 Claude Code 在会话中通过 mcp-find、mcp-add 和 mcp-exec 动态发现并调用服务器，适合探索未知工具。动态加入的服务器只对当前会话生效，不会持久化到 Profile。

该能力属于实验性功能。生产项目可关闭或限制它，避免**临时扩大工具范围；确定需要的服务器应经过评审后固定到 Profile。

第十一步 共享 Profile 给团队

Profile 可以导出到项目的 .docker 目录，也可以作为 OCI Artifact 推送到团队 Registry。共享内容包含服务器和配置，但不会包含 OAuth 或其他凭据。

团队成员拉取或导入后要单独授权账号。导出的配置应经过代码**和版本标记，避免 latest 漂移，并把用户专属的客户端连接文件加入 gitignore。

第十二步 在远程 Mac 保持会话

在远程 Mac 上运行 Docker Desktop、MCP Toolkit 和 Claude Code，可持续保留镜像缓存、Profile、仓库与 tmux 会话。连接断开后，开发环境和 Gateway 配置仍在远端。

远程主机使用独立系统账号、磁盘加密与短时 SSH 凭据。不要把 Docker socket 暴露到公网；文件挂载只指向必要项目目录，并定期清理不再使用的 OAuth、Secret、Profile 和容器镜像。

ssh your-**c-mini
cd /path/to/your-project
tmux new -s docker-mcp
claude

# 断线后接回
tmux attach -t docker-mcp

为什么 Zu**c Ai 适合这类工作流

根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，配置为 16G* 统一内存与 256G* SSD，支持终端、Tailscale、ToDesk、RustDesk，以及浏览器 SSH 或 VNC 等接入方式。

长期在线环境适合保留 Docker 镜像缓存、Profile、仓库、Claude Code 与 tmux 会话。外部服务账号、MCP ******、文件挂载、密钥、网络和审计责任仍由使用者及所属组织负责。

常见问题排查

结语

Docker MCP Toolkit 的核心价值是把服务器、配置、凭据和客户端连接集中到可**的 Profile 中。安全接入应从最小服务器集合开始，限制文件挂载与 OAuth 范围，先做只读验收，再为每类写入建立清晰确认边界。