devcontainer-mcp

io.github.aniongithubPublished by GitHub account aniongithubv0.40Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated 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.
Before you install
The agent can create, stop and delete containers, workspaces and codespaces, and write or overwrite files inside them. It can run arbitrary commands in those environments. The installer adds agent hooks that block host shell commands in repos with a devcontainer config; they fail open and can be disabled with a marker file or a bypass variable. Auth login opens a browser and stores credentials via the CLI keyrings.

Installation

In SourceWeft

  1. Open devcontainer-mcp in the dashboard and add it to a workspace.
  2. 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

[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

Source: README.md at commit 29a607c

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  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