devcontainer-mcp

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.

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

Linux / macOS

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

Windows (via WSL)

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:

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

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

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)

DevPod (19 tools)

devcontainer CLI (12 tools)

GitHub Codespaces (11 tools) — require auth handle

MCP Server Configuration

Linux / macOS

{

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

Windows (WSL bridge)

{

"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/ /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 (`