
devcontainer-mcp
io.github.aniongithub由 GitHub 账号 aniongithub 发布v0.40更新于 Oct 24, 2026
Manage dev container environments via MCP (Docker, DevPod, Codespaces).
概览
让 AI 编程代理在本地 Docker、DevPod 或 GitHub Codespaces 上创建、运行命令并管理隔离的开发容器。
- 可以做什么
- 创建、启动、构建、停止、删除和查看开发容器、DevPod 工作区与 Codespaces,并列出其状态和日志。通过 SSH 在容器或工作区内执行命令,并读取、写入、编辑和列出其中的文件。发现并读取 devcontainer.json 配置,包括多容器 compose 场景。通过认证代理管理账户:查询状态、登录、切换和登出 GitHub、AWS、Azure、GCP 与 Kubernetes。查看 DevPod 提供方、上下文和 Docker 容器详情。
- 适用场景
- 适合希望代理在可复现的容器中而非宿主机上构建、测试和运行代码的场景,或需要根据仓库的 devcontainer 配置启动云端或 Codespaces 环境时使用。
- 运行要求
- 以本地二进制运行(linux-x64、linux-arm64、darwin-x64、darwin-arm64);Windows 上需在 WSL 2 中运行并通过 wsl 启动。运行时检测后端命令行工具:devcontainer CLI 与 Docker、DevPod CLI,以及用于 Codespaces 的 GitHub CLI。云服务商需要账户,Codespaces 工具需要认证句柄。
安装
在 SourceWeft 中
- 打开 控制台中的 devcontainer-mcp,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
devcontainer-mcp
Give your AI agent its own dev environment — not yours.
devcontainer-mcp is an MCP server that lets AI coding agents create, manage, and work inside dev containers across three backends: local Docker, DevPod, and GitHub Codespaces. The agent builds, tests, and ships code in an isolated container — your laptop stays clean.
[devcontainer-mcp local Docker demo]
Works with GitHub Copilot, Claude, Cursor, opencode, and any MCP-compatible client.
The Problem
When AI agents write code, they need to run it somewhere. Today that means your host machine:
- 🔴 Host contamination — agents install packages, modify PATH, leave behind build artifacts
- 🔴 "Works on my machine" — agents assume your local toolchain matches production
- 🔴 No isolation — one project's dependencies break another
- 🔴 Security risk — agents run arbitrary commands with your user privileges
- 🔴 Hardware constraints — you're limited to your local machine's resources
The Solution
The devcontainer spec already defines reproducible, container-based dev environments. Every major project ships a .devcontainer/devcontainer.json. But AI agents can't use them — until now.
devcontainer-mcp exposes 45 MCP tools that let any AI agent:
- Spin up a dev container from any repo — locally, on a cloud VM, or in Codespaces
- Run commands inside the container — builds, tests, linting, anything
- Manage the lifecycle — stop, restart, delete when done
- Authenticate against cloud providers — GitHub, AWS, Azure, GCP — without ever seeing a raw token
Quick Install
[devcontainer-mcp install demo]
Linux / macOS
Windows (via WSL)
How it works: The binary runs inside WSL; MCP clients on Windows launch it via
wsl ~/.local/bin/devcontainer-mcp serve. The stdio transport works transparently across the WSL boundary. WSL 2 is required — install it withwsl --installif you haven't already.
Backend CLIs (devpod, devcontainer, gh) are detected at runtime — if one is missing, the MCP server returns a helpful error with install instructions.
Binaries available for linux-x64, linux-arm64, darwin-x64, and darwin-arm64.
Host Protection & Opt-Out
The installer configures two agent hooks (Claude Code & GitHub Copilot CLI) that activate only in a directory containing .devcontainer/devcontainer.json:
devcontainer-guard(PreToolUse) — blocks shell/command execution on the host so the agent routes builds, tests, and runs through the MCP tools instead. Host-safe commands (git,gh) are allowlisted, and both hooks fail open — ifjqis missing or a payload can't be parsed, commands are allowed rather than blocked.devcontainer-skill-loader(SessionStart) — injects theSKILL.mdusage guide as context.
Turning it off for a repo
Sometimes a project ships a stale or unmaintained .devcontainer that you don't actually want to route work through. To disable both hooks for that repo, drop a marker file at the repo root:
When .devcontainer-mcp-disable is present, the guard allows host commands through and the skill-loader skips context injection — the agent works locally as if no devcontainer were declared. Commit it (or add it to .gitignore for a local-only opt-out).
One-off bypass: to run a single host command without disabling the guard, include USER_CONFIRMED_HOST_OPERATION=1 anywhere in the command.
Architecture
Three Backends, One Interface
[devcontainer-mcp Codespaces demo]
Auth Broker
The agent never sees raw tokens. Instead:
auth_status(provider)— list available accounts and scopesauth_login(provider, scopes?)— initiate login, opens browser, handles device codesauth_select(id)— switch the active accountauth_logout(id)— revoke credentials
Codespaces tools require an auth handle (e.g. "github-aniongithub"). The MCP server resolves it to the real token on each call via the CLI's native keyring.
Supported providers: GitHub, AWS, Azure, GCP, Kubernetes
MCP Tools (46 total)
Auth (4 tools)
DevPod (19 tools)
devcontainer CLI (12 tools)
GitHub Codespaces (11 tools) — require auth handle
MCP Server Configuration
Linux / macOS
Windows (WSL bridge)
Prerequisites
Install backend CLIs as needed — the MCP server detects them at runtime and returns helpful errors if missing:
- devcontainer CLI:
npm install -g @devcontainers/cli+ Docker - DevPod: DevPod CLI + Docker (or another provider)
- Codespaces: GitHub CLI — auth is handled by the
auth_logintool
Self-Healing
When devcontainer_up, devpod_up, or codespaces_create fails, the full build output (including errors) is returned to the agent. The agent can read the error, fix the Dockerfile or devcontainer.json, and retry — making the dev environment a dynamic, agent-managed asset rather than a static prerequisite.
Multi-container workspaces
The devcontainer spec supports connecting to multiple containers in one workspace by placing per-service configs at .devcontainer/<name>/devcontainer.json, each pointing at a shared docker-compose.yml. devcontainer-mcp supports this pattern end-to-end:
- Discovery —
devcontainer_list_configsreturns every config it finds (root.devcontainer.json,.devcontainer/devcontainer.json, and each.devcontainer/*/devcontainer.json) with its kind (image/dockerfile/compose), service name, and absolute path. - Targeting — Every devcontainer tool (
up,exec,build,stop,remove,status,read_config,file_*) accepts an optionalconfigparameter pointing at a specificdevcontainer.json. Single-container workflows continue to work unchanged —configdefaults to whatever the devcontainer CLI auto-detects. - Ambiguity handling — When a workspace has multiple configs and no
configis provided, lookup-style tools (status,exec,stop,remove,file_*) return a structuredAmbiguousresult listing every matching container so the agent can pick the right one.statusreports this as{"state":"Ambiguous","candidates":[...],"hint":"..."}. - Robust container matching — Sibling compose containers are identified via
com.docker.compose.service+com.docker.compose.project.config_files(not the unreliabledevcontainer.local_folderlabel, which is only stamped on the first container).
Development
This project eats its own dogfood — development happens inside its own devcontainer.
CI/CD
- Pull Requests —
cargo check,cargo test,cargo clippy,cargo fmtrun automatically - Releases — Creating a GitHub release builds binaries for all 4 platforms
License
来源:README.md,提交 29a607c
工具
0版本历史
1- v0.40最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分