mcp-devcontainers

This MCP server generates and configures development containers directly from devcontainer.json files. It leverages the devcontainers/cli tooling to initialize, run, and manage devcontainer environments, enabling you to spin up consistent development environments from container definitions. The server exposes several tools under the MCP transport, including commands to initialize a container, run user-defined setup steps, execute arbitrary shell commands inside the container, clean up environments, list active environments, and discover workspace folders containing devcontainer configurations. You can run the server in stdio mode, or enable streaming transports (SSE or Streamable HTTP) for remote clients. The tooling is designed to work with standard devcontainer configurations and integrates with the MCP inspector for remote monitoring and control.

Key capabilities:

• devcontainer_up: Initialize and start a devcontainer in a specified workspace folder.
• devcontainer_run_user_commands: Run post-create and post-start scripts inside the devcontainer.
• devcontainer_exec: Execute arbitrary shell commands inside the running devcontainer.
• devcontainer_cleanup: Remove or stop all devcontainer environments.
• devcontainer_list: List current devcontainer environments and statuses.
• devcontainer_workspace_folders: Discover workspace folders under a root path that contain a devcontainer configuration.

To use, connect to the server via one of the transports (stdio, SSE, or HTTP) and invoke the desired devcontainer_* tool with the required parameters. If you’re testing remotely, you can reference a workspace folder path or a rootPath to locate relevant configurations, and the tools will return textual output describing startup information, command results, or status updates.

Prerequisites:

• Node.js 20+ (as indicated by the project badge)
• Docker installed and available in your environment (required for running devcontainers)

Installation steps:

1. Install dependencies and build (if sourcing from source):

npm install
npm run build

2. Run locally via npx (recommended for quick testing):

npx -y mcp-devcontainers

3. Install as a project dependency (optional):

npm install mcp-devcontainers --save

4. Start in different transports (examples):

• Standard IO transport (default):

npm start

• Server-Sent Events (SSE):

npm start sse

• Streamable HTTP:

npm start http

Notes:

• Ensure Docker is running before starting the MCP server when using devcontainer functionality.
• The repository supports local development via npx to avoid global installs; for persistent usage, consider adding as a project dependency or wrapper script.

Tips and common issues:

• Docker must be running in the environment where the MCP server executes; without Docker, devcontainer operations will fail.
• When using remote tooling (SSE/HTTP), ensure appropriate network access and port forwarding for the transport endpoint.
• The server relies on devcontainers/cli tooling; if you encounter issues starting a devcontainer, check that devcontainer.json configurations are valid and reachable from the workspace folder.
• If using Codespaces or remote environments, sometimes startup may take longer; increase inspector timeouts if awaiting results in a single response.
• The mcp-inspector can be used with streamable HTTP to connect and monitor output; append /mcp to the URL when using a streamable HTTP transport.