devcontainer-mcp

io.github.aniongithub由 GitHub 账号 aniongithub 发布v0.40更新于 Oct 24, 2026

Manage dev container environments via MCP (Docker, DevPod, Codespaces).

概览

AI 生成的概览

让 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 工具需要认证句柄。
安装前请注意
代理可以创建、停止和删除容器、工作区与 codespaces,并可在其中写入或覆盖文件,也能在这些环境里执行任意命令。安装程序会添加代理钩子,在含 devcontainer 配置的仓库中阻止宿主机 shell 命令;钩子失败时放行,可用标记文件或绕过变量关闭。认证登录会打开浏览器,凭据由各命令行工具自身的密钥环保存。

安装

在 SourceWeft 中

  1. 打开 控制台中的 devcontainer-mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

devcontainer-mcp

[CI] [Website]

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:

  1. Spin up a dev container from any repo — locally, on a cloud VM, or in Codespaces
  2. Run commands inside the container — builds, tests, linting, anything
  3. Manage the lifecycle — stop, restart, delete when done
  4. Authenticate against cloud providers — GitHub, AWS, Azure, GCP — without ever seeing a raw token
Agent: "Let me build this project..."  → auth_status("github") → picks account  → codespaces_create(auth: "github-you", repo: "your/repo")  → codespaces_ssh(auth: "github-you", codespace: "...", command: "cargo build")  → ✅ Built in the cloud. Your laptop did nothing.

Quick Install

[devcontainer-mcp install demo]

Linux / macOS

bash
curl -fsSL https://raw.githubusercontent.com/aniongithub/devcontainer-mcp/main/install.sh | bash

Windows (via WSL)

powershell
Invoke-RestMethod https://github.com/aniongithub/devcontainer-mcp/releases/latest/download/install.ps1 | Invoke-Expression

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 with wsl --install if 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 — if jq is missing or a payload can't be parsed, commands are allowed rather than blocked.
  • devcontainer-skill-loader (SessionStart) — injects the SKILL.md usage 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:

bash
touch .devcontainer-mcp-disable

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

mermaid
graph TD    A[AI Agent / MCP Client] -->|stdio JSON-RPC| B[devcontainer-mcp]        subgraph "devcontainer-mcp"        B --> C[33 MCP Tools]        C --> D[Auth Broker]        C --> E[devcontainer-mcp-core]    end        D -->|opaque handles| C    E -->|subprocess| F[DevPod CLI]    E -->|subprocess| G[devcontainer CLI]    E -->|subprocess| H[gh CLI]    E -->|bollard API| I[Docker Engine]        F --> J[Docker / K8s / Cloud VMs]    G --> K[Local Docker]    H --> L[GitHub Codespaces]

Three Backends, One Interface

[devcontainer-mcp Codespaces demo]

BackendBest forRequiresAuth needed?
devcontainer CLI (devcontainer_*)Local Docker — fast, simple@devcontainers/cli + DockerNo
DevPod (devpod_*)Multi-cloud: Docker, K8s, AWS, Azure, GCPDevPod CLIOptional (cloud providers)
Codespaces (codespaces_*)GitHub-hosted cloud environmentsgh CLIYes (auth handle)

Auth Broker

The agent never sees raw tokens. Instead:

  1. auth_status(provider) — list available accounts and scopes
  2. auth_login(provider, scopes?) — initiate login, opens browser, handles device codes
  3. auth_select(id) — switch the active account
  4. auth_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)

ToolDescription
auth_statusCheck auth for a provider — returns handles, accounts, scopes
auth_loginInitiate login or refresh scopes — browser + device code flow
auth_selectSwitch the active account for a provider
auth_logoutRevoke credentials for an account

DevPod (19 tools)

ToolDescription
devpod_upCreate and start a workspace from a git URL, local path, or image
devpod_stopStop a running workspace
devpod_deleteDelete a workspace and its resources
devpod_buildBuild a workspace image without starting it
devpod_statusGet workspace state (Running, Stopped, Busy, NotFound)
devpod_listList all workspaces with IDs, sources, providers, and status
devpod_sshExecute a command inside a workspace via SSH
devpod_logsGet workspace logs
devpod_provider_listList all configured providers
devpod_provider_addAdd a new provider
devpod_provider_deleteRemove a provider
devpod_context_listList all contexts
devpod_context_useSwitch to a different context
devpod_container_inspectDocker inspect — labels, ports, mounts, state
devpod_container_logsStream container logs via Docker API
devpod_file_readRead file content with optional line range
devpod_file_writeCreate or overwrite a file (auto-creates parent dirs)
devpod_file_editSurgical string replacement — old_str → new_str
devpod_file_listList directory contents (non-hidden, 2 levels deep)

devcontainer CLI (12 tools)

ToolDescription
devcontainer_upCreate and start a local dev container
devcontainer_execExecute a command inside a running dev container
devcontainer_buildBuild a dev container image
devcontainer_read_configRead merged devcontainer configuration as JSON
devcontainer_list_configsDiscover all devcontainer.json files in a workspace (single + multi-container)
devcontainer_stopStop a dev container (via Docker API)
devcontainer_removeRemove a dev container and its resources
devcontainer_statusGet dev container state by workspace folder
devcontainer_file_readRead file content with optional line range
devcontainer_file_writeCreate or overwrite a file (auto-creates parent dirs)
devcontainer_file_editSurgical string replacement — old_str → new_str
devcontainer_file_listList directory contents (non-hidden, 2 levels deep)

GitHub Codespaces (11 tools) — require auth handle

ToolDescription
codespaces_createCreate a new codespace for a repository
codespaces_listList your codespaces with state and machine info
codespaces_sshExecute a command inside a codespace via SSH
codespaces_stopStop a running codespace
codespaces_deleteDelete a codespace
codespaces_viewView detailed codespace info (state, machine, config)
codespaces_portsList forwarded ports with visibility and URLs
codespaces_file_readRead file content with optional line range
codespaces_file_writeCreate or overwrite a file (auto-creates parent dirs)
codespaces_file_editSurgical string replacement — old_str → new_str
codespaces_file_listList directory contents (non-hidden, 2 levels deep)

MCP Server Configuration

Linux / macOS

json
{  "mcpServers": {    "devcontainer-mcp": {      "command": "devcontainer-mcp",      "args": ["serve"]    }  }}

Windows (WSL bridge)

json
{  "mcpServers": {    "devcontainer-mcp": {      "command": "wsl",      "args": ["~/.local/bin/devcontainer-mcp", "serve"]    }  }}

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_login tool

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_configs returns 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 optional config parameter pointing at a specific devcontainer.json. Single-container workflows continue to work unchanged — config defaults to whatever the devcontainer CLI auto-detects.
  • Ambiguity handling — When a workspace has multiple configs and no config is provided, lookup-style tools (status, exec, stop, remove, file_*) return a structured Ambiguous result listing every matching container so the agent can pick the right one. status reports 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 unreliable devcontainer.local_folder label, which is only stamped on the first container).

Development

This project eats its own dogfood — development happens inside its own devcontainer.

bash
# Using the devcontainer CLIdevcontainer up --workspace-folder .devcontainer exec --workspace-folder . cargo build --workspacedevcontainer exec --workspace-folder . cargo test --workspacedevcontainer exec --workspace-folder . cargo build --release -p devcontainer-mcp
# Or using DevPoddevpod up . --id devcontainer-mcp --provider docker --open-ide=falsedevpod ssh devcontainer-mcp --command "cd /workspaces/devcontainer-mcp && cargo build --workspace"

CI/CD

  • Pull Requests — cargo check, cargo test, cargo clippy, cargo fmt run automatically
  • Releases — Creating a GitHub release builds binaries for all 4 platforms

License

MIT

来源:README.md,提交 29a607c

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.40最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分