
devcontainer-mcp
io.github.aniongithubPublished by GitHub account aniongithubv0.40Updated Oct 24, 2026
Manage dev container environments via MCP (Docker, DevPod, Codespaces).
Overview
Lets an AI coding agent create, run commands in, and manage isolated dev containers on local Docker, DevPod, or GitHub Codespaces.
- What you can do
- Create, start, build, stop, remove and inspect dev containers, DevPod workspaces and Codespaces, and list their status and logs. Run commands inside a container or workspace over SSH, and read, write, edit and list files there. Discover and read devcontainer.json configs, including multi-container compose setups. Manage provider accounts through an auth broker: check status, log in, select and log out for GitHub, AWS, Azure, GCP and Kubernetes. Inspect DevPod providers, contexts and Docker container details.
- When to use it
- Useful when an agent should build, test and run code in a reproducible container instead of on the host machine, or when you want it to spin up cloud or Codespaces environments from a repository's devcontainer config.
- Requirements
- Runs as a local binary (linux-x64, linux-arm64, darwin-x64, darwin-arm64); on Windows it runs inside WSL 2 and is launched through wsl. Backend CLIs are detected at runtime: devcontainer CLI with Docker, DevPod CLI, and the GitHub CLI for Codespaces. Cloud providers need accounts; Codespaces tools need an auth handle.
Installation
In SourceWeft
- Open devcontainer-mcp in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
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
Source: README.md at commit 29a607c
Tools
0Version history
1- v0.40LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts