DevContainer MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI-powered DevContainer management. This server allows developers to create, configure, build, test, and modify DevContainer environments using natural language prompts through VS Code, Cursor, or any MCP-compatible editor.

- Natural Language Processing: Convert plain English descriptions into validdevcontainer.jsonconfigurations
- Template System: 11+ pre-built templates for popular development stacks (Node.js, Python, Go, Rust, Java, etc.)
- Container Management: Build, test, start, stop, and monitor DevContainers using DevContainer CLI
- Live Modification: Update existing configurations based on natural language requests
- Status Monitoring: Real-time container health and configuration status
- Multi-Editor Support: Compatible with VS Code, Cursor, Claude Desktop, and other MCP clients
- CLI Tool: Standalone command-line interface for direct usage

- Installation
- Configuration
- Usage Examples
- Available Tools
- Templates
- CLI Tool
- Troubleshooting
- API Reference
- Contributing

git clone https://github.com/Siddhant-K-code/mcp-devcontainer.git cd mcp-devcontainer npm install npm run build

{ "mcp.servers": { "devcontainer": { "command": "devcontainer-mcp-server", "args": [], "env": {} } } }

{ "mcp": { "servers": { "devcontainer": { "command": "devcontainer-mcp-server" } } } }

Add to~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or equivalent:

{ "mcpServers": { "devcontainer": { "command": "devcontainer-mcp-server", "args": [] } } }

"Create a React TypeScript project with Tailwind CSS on port 3000"

"Python Django web application with PostgreSQL database and Redis cache"

"Go API server with Gin framework, PostgreSQL database, and Docker support on port 8080"

"MEAN stack development environment with MongoDB, Express, Angular, and Node.js"

The system automatically detects technologies and generates appropriate configurations:

- Languages: JavaScript, TypeScript, Python, Go, Rust, Java, PHP, Ruby
- Frameworks: React, Angular, Vue, Express, Django, Flask, Spring, Rails
- Databases: PostgreSQL, MySQL, MongoDB, Redis, SQLite, Elasticsearch
- Tools: Docker, Git, development tools, VS Code extensions
- Ports: Automatic port detection and forwarding

Generate DevContainer configuration from natural language.

- prompt(required): Natural language description
- workspaceRoot(optional): Workspace path (default: ".")
- baseTemplate(optional): Template to start from

- workspaceRoot(optional): Workspace path (default: ".")
- configPath(optional): Custom config path
- rebuild(optional): Force rebuild (default: false)

- workspaceRoot(optional): Workspace path (default: ".")
- testCommands(optional): Custom test commands array

- workspaceRoot(optional): Workspace path (default: ".")
- modifications(required): Desired changes description

- workspaceRoot(optional): Workspace path (default: ".")

- nodejs-typescript: Node.js with TypeScript support
- python: Python with common packages and debugging
- go: Go development with standard tooling
- rust: Rust environment with Cargo and debugging
- java: Java with Maven/Gradle support
- php: PHP with Composer and debugging
- ruby: Ruby with Rails support

- react: Modern React development stack with TypeScript and Vite

- mean-stack: MongoDB, Express, Angular, Node.js
- docker-compose: Multi-service development

- universal: Multi-language development environment

- Appropriate base image and runtime
- Language-specific tools and debuggers
- Recommended VS Code extensions
- Common port forwarding
- Package manager setup commands

The package includes a standalone CLI tool for direct usage:

devcontainer-mcp-cli generate "React TypeScript app with Tailwind CSS"

devcontainer-mcp-cli build --workspace . --rebuild

devcontainer-mcp-cli test --command "npm test" --command "npm run lint"

devcontainer-mcp-cli templates --category backend

devcontainer-mcp-cli status --workspace .

devcontainer-mcp-cli modify "add Redis support and port 6379"

- Ensure Docker Desktop is running
- Check Docker daemon status:docker info

- Check devcontainer.json syntax
- Verify base image availability
- Review build logs for specific errors

- Ensure Docker has proper permissions
- Check file system permissions for workspace

- Try with a more specific prompt
- Uselist_templatesto see available options
- Specify a base template explicitly

"DevContainer configuration not found":

- Generate configuration first withgenerate_devcontainer
- Check.devcontainer/devcontainer.jsonexists

- Check internet connection for image downloads
- Consider using lighter base images
- Increase timeout if needed for large images

The server implements the Model Context Protocol specification:

- Tool registration with complete schemas
- Proper request/response handling
- Error responses in MCP format
- Text content responses

All tools return structured responses with:

- Success/failure status
- Detailed output and error messages
- Reasoning for configuration choices
- Generated configurations in JSON format

- Invalid configurations
- Build failures
- CLI availability issues
- File system errors
- Network timeouts

npm test -- config-generator.test.ts npm test -- template-manager.test.ts npm test -- devcontainer-manager.test.ts

src/ ├── index.ts # Main MCP server ├── config-generator.ts # Natural language processing ├── devcontainer-manager.ts # Container operations ├── template-manager.ts # Template management ├── cli.ts # CLI tool └── __tests__/ # Test suite

npm run build # Compile TypeScript npm run dev # Development mode npm run start # Production mode npm run lint # Code linting

- Editsrc/template-manager.ts
- Add template configuration to the templates array
- Include appropriate metadata (languages, frameworks, category)
- Add tests for the new template
- Update documentation
- Update language patterns inconfig-generator.ts
- Add framework detection patterns
- Map to appropriate VS Code extensions
- Create or update templates as needed
- Add test cases

We welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Ensure all tests pass
- Submit a pull request
- Install dependencies:npm install
- Run tests:npm test
- Build project:npm run build
- Test CLI:npm run cli -- --help

MIT License - seeLICENSEfile for details.

- DevContainer CLIfor container management
- Model Context Protocolfor the protocol specification
- VS Code DevContainersfor the container standards

A reverse proxy gateway for managing and accessing multiple MCP servers through a single entry point, deployable via Docker.