Devcontainer MCP Server for Generating Dev Containers

Overview

The Devcontainer MCP Server is a lightweight Model Context Protocol (MCP) service that generates, validates, and serves development container configurations (devcontainers) from existing devcontainer configuration files. It reads standard devcontainer manifests (.devcontainer/, devcontainer.json, Dockerfile, etc.), validates and optionally augments them, and returns an assembled devcontainer package that can be used with VS Code Remote - Containers, GitHub Codespaces, or other containerized development workflows.

This server is useful for teams that want to automate creation and distribution of reproducible development environments. It can run as a local service in developer machines, in CI pipelines, or as a component of an AI toolchain that uses MCP-compatible agents to produce, modify, or inspect devcontainer artifacts programmatically.

GitHub: https://github.com/AI-QL/mcp-devcontainers

Features

• Parse and validate devcontainer configuration files (devcontainer.json, Dockerfile, devcontainer.yaml)
• Generate a packaged devcontainer archive or file tree for consumption by editors and CI
• Expose MCP-compatible endpoints so LLM agents and tools can request devcontainer operations
• Provide file storage and retrieval for artifacts (tarballs, ZIPs, config files)
• Basic security: API key support and optional CORS / host binding controls
• CLI and Docker-friendly deployment options for local or server use

Installation / Configuration

Prerequisites:

• Node.js 18+ (or compatible runtime)
• Docker (optional; required only if you want to run container builds)

Clone and install:

git clone https://github.com/AI-QL/mcp-devcontainers.git
cd mcp-devcontainers
npm install

Run locally (development):

# start server on default port (3000)
npm run start

Run as a Docker container:

# build
docker build -t mcp-devcontainers:latest .

# run (exposes port 3000, persists workspace in ./data)
docker run -p 3000:3000 -v $(pwd)/data:/app/data mcp-devcontainers:latest

Environment variables:

PORT=3000                # HTTP port to listen on
STORAGE_DIR=./data       # directory to persist files/artifacts
API_KEY=                  # optional API key for requests
ALLOW_PUBLIC_ACCESS=false # optional toggle for unsecured access

Example systemd unit (minimal):

[Unit]
Description=MCP Devcontainers Server

[Service]
WorkingDirectory=/opt/mcp-devcontainers
ExecStart=/usr/bin/npm start
Environment=PORT=3000 STORAGE_DIR=/var/lib/mcp-devcontainers API_KEY=supersecret
Restart=always

[Install]
WantedBy=multi-user.target

Available Resources

The server exposes HTTP endpoints and MCP-compatible tooling endpoints. Below is a summary of the most commonly used endpoints.

MCP Request Example (JSON):

{
  "id": "req-123",
  "tool": "devcontainer-generator",
  "action": "generate",
  "inputs": {
    "source": "https://github.com/example/repo",
    "entry": ".devcontainer/devcontainer.json",
    "options": {
      "packageArtifacts": true,
      "includeDockerfile": true
    }
  }
}

Use Cases

1. Onboarding automation

   • Scenario: A large team has many repositories with slightly different devcontainer configs. Run the MCP server in your CI or internal service to validate and package per-repo devcontainers and provide a single downloadable artifact to new hires.
   • Flow: CI triggers /mcp/v0 generate → server validates and produces a tarball → artifact is uploaded to internal storage and a link is published.

2. LLM-assisted devcontainer creation

   • Scenario: An AI tool analyzes a project and needs to produce a devcontainer tailored to the project’s stack (Node, Python, Rust).
   • Flow: The tool calls the MCP /mcp/v0 endpoint with “generate” action and a set of constraints (ports, extensions, packages). The server assembles a devcontainer.json + Dockerfile and returns an archive.

3. Reproducible CI builds

   • Scenario: You want CI pipelines to build inside the exact devcontainer used by developers.
   • Flow: CI queries the MCP server for the devcontainer package, extracts it in the pipeline workspace, and uses the same Dockerfile for caching and deterministic builds.

4. Batch validation and auditing

   • Scenario: Security team needs to check all devcontainer configurations across repositories for granted privileges or unsafe settings.
   • Flow: Submit multiple /validate requests; server returns diagnostics and suggestions to remediate problematic entries.

Tips and Recommendations

• Use the API_KEY environment variable in production to limit access to the MCP endpoints.
• Persist STORAGE_DIR to avoid losing uploaded artifacts across restarts.
• Combine the MCP server with a reverse proxy (nginx) to add TLS and rate-limiting in front of the service.
• Start by running the service locally and using the /generate endpoint with a single repository to understand output structure.

For full API details, contribution guidelines, and examples, see the project repository: https://github.com/AI-QL/mcp-devcontainers