MCP Devcontainers

MCP server for devcontainer to generate and configure development containers directly from devcontainer.json configuration files.

📌 Pre-condition

This project is built with Node.js. For local development, you can either:

• Install `Node.js` on your machine, or
• Use the provided devcontainer virtual environment.

You may run the project without installing `Node.js` locally by using `npx`:

npx -y mcp-devcontainers

Docker is required in the execution environment:

• For local MCP server: Install Docker on your local machine
• For remote MCP server: Install Docker on the remote server

> 📦 Docker installation guide: https://docs.docker.com/get-started/get-docker/

🚀 Getting Started

• Build: `npm run build` - Compiles TypeScript to JavaScript
• Watch mode: `npm run watch` - Automatically rebuilds on file changes
• Prepare release: `npm run prepare` - Prepares the package for publishing
• Run ESLint: `npm run lint` - Executes ESLint for code validation
• Fix ESLint issues: `npm run lint:fix` - Automatically fixes ESLint errors

✨ MCP Transport

Option 1 - Start STDIO server

Launches the MCP server with stdio transport

npm start

Option 2 - Start SSE server

Runs the MCP server with Server-Sent Events transport on `https://{your-domain}/sse`

npm start sse

Option 3 - Start Streamable HTTP server

Starts the MCP server with Streamable HTTP transport on `https://{your-domain}/mcp`

npm start http

📚 Tools

Tools are built on the devcontainers/cli

They enable you to generate and configure development containers directly from `devcontainer.json` configuration files:

`devcontainer_up`

Initializes and starts a devcontainer environment in the specified workspace folder. Ensures the devcontainer is operational and ready for development tasks.

• #### Input Parameters

• #### Returns

Text content with the devcontainer startup information

`devcontainer_run_user_commands`

Executes user-defined postCreateCommand and postStartCommand scripts within the devcontainer for the specified workspace. Use this to run setup or initialization tasks after container startup.

• #### Input Parameters

• #### Returns

Text content with the command execution result

`devcontainer_exec`

Runs a custom shell command inside the devcontainer for the specified workspace. Useful for executing arbitrary commands or scripts within the devcontainer environment.

• #### Input Parameters

• #### Returns

Text content with the command execution result

`devcontainer_cleanup`

Runs docker command to cleanup all devcontainer environments.

• #### Input Parameters

N/A

• #### Returns

Text content with Docker process ID removed

`devcontainer_list`

Runs docker command to list all devcontainer environments.

• #### Input Parameters

N/A

• #### Returns

Text content with the current devcontainer Docker process status

`devcontainer_workspace_folders`

Runs find command to get all workspace folders with devcontainer config.

• #### Input Parameters

• #### Returns

Text content with all workspace folders under the specified root path.

🧑‍💻 Quick Experience / Trial

For developers who want to quickly try this project without a local Docker setup, we recommend using GitHub Codespaces:

Then follow these steps to set up a trial environment:

• Wait for the environment to initialize in your browser

• Install dependencies: `npm install`

• Launch the service: `npm start http`

> The codespace will automatically provide a forwarded port (e.g., https://ominous-halibut-7vvq7v56vgq6hr5p9-3001.app.github.dev/)

• Make the `forwarded port` publicly accessible (located on the right side of the VSCode `Terminal` tab)

• Connect using mcp-inspector via Streamable HTTP

npx -y @modelcontextprotocol/inspector

> For a streamable HTTP connection, remember to append `/mcp` to the URL

> `devcontainer_up` typically takes a considerable amount of time to start the container. If you want to receive the result within a single response interaction, you will need to increase both the `Request Timeout` and the `Maximum Total Timeout` in the `Configuration` of the `mcp-inspector`

For MCP Clients that don't support remote URLs, use this alternative configuration:

{
  "mcpServers": {
    "Devcontainer": {
      "command": "npx",
      "args": ["mcp-remote", "https://ominous-halibut-7vvq7v56vgq6hr5p9-3001.app.github.dev/mcp"]
    }
  }
}

🤝 Contributing

We welcome contributions of any kind to this project, including feature enhancements, UI improvements, documentation updates, test case completions, and syntax corrections. I believe that a real developer can write better code than AI, so if you have concerns about certain parts of the code implementation, feel free to share your suggestions or submit a pull request.

Please review our Code of Conduct. It is in effect at all times. We expect it to be honored by everyone who contributes to this project.

For more information, please see Contributing Guidelines

🐞 Opening an Issue

Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first.

🔒 Reporting Security Issues

Review our Security Policy. Do not file a public issue for security vulnerabilities.

⭐ Credits

Written by @AIQL.com.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.