Claude Code Docker MCP Toolkit 接入教程
用 Profile 和 Gateway 集中管理容器化 MCP 工具
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. 不创建 不更新 不删除 不发送 不部署任何资源| 验收项 | 通过标准 |
|---|---|
| 客户端 | MCP_DOCKER 显示 Connected |
| Profile | 连接的是 docker-dev |
| 服务器 | 只有批准的测试服务器 |
| 凭据 | 账号与授权范围正确 |
| 结果 | 只读任务成功且无外部写入 |
第九步 为写入工具建立确认边界
GitHu*、项目管理、数据库和部署类服务器常含写入工具。每次执行前让 Claude Code 展示目标资源 ID、动作、字段变化、影响范围和回滚方式。
先用读取工具确认现状，再执行一项小变更并重新读取验证。删除、合并、发布、部署、支付和权限修改应保持人工逐项确认。
| 操作 | 风险 | 控制方式 |
|---|---|---|
| 读取公开文档 | 低 | 限制服务器和返回数量 |
| 读取**仓库或工单 | 中 | 使用最小 OAuth 范围 |
| 挂载项目目录 | 中 | 仅必要子目录并优先只读 |
| 创建 Issue 或修改代码 | 高 | 展示差异并逐项确认 |
| 部署 支付 权限变更 | 极高 | 独立审批和操作后复核 |
第十步 使用 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 ******、文件挂载、密钥、网络和审计责任仍由使用者及所属组织负责。
常见问题排查
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
| 找不到 MCP Toolkit | Docker Desktop 版本过旧 | 升级到 4.62 或更高版本 |
| docker mcp 命令不可用 | Toolkit 未启用或 CLI 版本不匹配 | 重启 Desktop 并核对版本 |
| MCP_DOCKER 未连接 | 客户端配置或 Profile 错误 | 重新 Connect 并运行 claude mcp list |
| 服务器没有工具 | 服务器未加入 Profile 或认证未完成 | 检查 Profile 和 Configuration |
| OAuth 使用了错误账号 | 凭据在 Profile 间共享 | 撤销后用正确账号重新授权 |
| 工具无法读取文件 | 未授予挂载或路径不正确 | 只授权必要目录并重新测试 |
结语
Docker MCP Toolkit 的核心价值是把服务器、配置、凭据和客户端连接集中到可**的 Profile 中。安全接入应从最小服务器集合开始，限制文件挂载与 OAuth 范围，先做只读验收，再为每类写入建立清晰确认边界。
