AI-QL/mcp-devcontainers

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 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

  Name	Required	Type	Description
  workspaceFolder	⚫	string	Path to the workspace folder
  outputFilePath	⚪	string	Path for output logs

• 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

  Name	Required	Type	Description
  workspaceFolder	⚫	string	Path to the workspace folder
  outputFilePath	⚪	string	Path for output logs

• 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

  Name	Required	Type	Description
  workspaceFolder	⚫	string	Path to the workspace folder
  outputFilePath	⚪	string	Path for output logs
  command	⚫	string[ ]	Command to execute as string array

• 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

  Name	Required	Type	Description
  rootPath	⚪	string	A path used to search its subdirectories for all workspace folders containing a devcontainer configuration.

• 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 . 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

🐞 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 . 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 file for details.