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.

🌟 Features

Natural Language Processing: Convert plain English descriptions into valid devcontainer.json configurations
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

Prerequisites

Node.js 18+
Docker or Podman
DevContainer CLI: npm install -g @devcontainers/cli

Install Package

npm install -g devcontainer-mcp-server

Development Installation

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

⚙️ Configuration

VS Code Setup

Add to your VS Code settings.json:

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

Cursor Setup

Add to your Cursor configuration:

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

Claude Desktop Setup

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

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

📚 Usage Examples

Natural Language Prompts

Generate a React TypeScript project:

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

Python Django with PostgreSQL:

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

Go microservice:

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

Full-stack MEAN application:

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

Expected Outputs

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

🛠️ Available Tools

1. `generate_devcontainer`

Generate DevContainer configuration from natural language.

Parameters:

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

2. `build_devcontainer`

Build container from configuration.

Parameters:

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

3. `test_devcontainer`

Test container functionality.

Parameters:

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

4. `list_templates`

Show available templates.

Parameters:

category (optional): Filter by category

5. `modify_devcontainer`

Modify existing configuration.

Parameters:

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

6. `get_devcontainer_status`

Check container status.

Parameters:

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

📦 Templates

Backend Templates

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

Frontend Templates

react: Modern React development stack with TypeScript and Vite

Full-Stack Templates

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

Universal Templates

universal: Multi-language development environment

Template Features

Each template includes:

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

🖥️ CLI Tool

The package includes a standalone CLI tool for direct usage:

Generate Configuration

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

Build Container

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

Test Container

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

List Templates

devcontainer-mcp-cli templates --category backend

Check Status

devcontainer-mcp-cli status --workspace .

Modify Configuration

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

🐛 Troubleshooting

Common Issues

DevContainer CLI not found:

npm install -g @devcontainers/cli

Docker not running:

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

Build failures:

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

Permission issues:

Ensure Docker has proper permissions
Check file system permissions for workspace

Error Messages

"No suitable template found":

Try with a more specific prompt
Use list_templates to see available options
Specify a base template explicitly

"DevContainer configuration not found":

Generate configuration first with generate_devcontainer
Check .devcontainer/devcontainer.json exists

"Build timeout":

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

📖 API Reference

MCP Protocol Compliance

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

Response Format

All tools return structured responses with:

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

Error Handling

Comprehensive error handling for:

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

🧪 Testing

Run the test suite:

npm test

Run with coverage:

npm run test:coverage

Test specific components:

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

🏗️ Development

Project Structure

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

Build and Run

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

Adding New Templates

Edit src/template-manager.ts
Add template configuration to the templates array
Include appropriate metadata (languages, frameworks, category)
Add tests for the new template
Update documentation

Adding Language Support

Update language patterns in config-generator.ts
Add framework detection patterns
Map to appropriate VS Code extensions
Create or update templates as needed
Add test cases

🤝 Contributing

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

Development Workflow

Install dependencies: npm install
Run tests: npm test
Build project: npm run build
Test CLI: npm run cli -- --help

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

DevContainer CLI for container management
Model Context Protocol for the protocol specification
VS Code DevContainers for the container standards

DevContainer MCP Server

DevContainer MCP Server

🌟 Features

📋 Table of Contents

🚀 Installation

Prerequisites

Install Package

Development Installation

⚙️ Configuration

VS Code Setup

Cursor Setup

Claude Desktop Setup

📚 Usage Examples

Natural Language Prompts

Expected Outputs

🛠️ Available Tools

1. generate_devcontainer

2. build_devcontainer

3. test_devcontainer

4. list_templates

5. modify_devcontainer

6. get_devcontainer_status

📦 Templates

Backend Templates

Frontend Templates

Full-Stack Templates

Universal Templates

Template Features

🖥️ CLI Tool

Generate Configuration

Build Container

Test Container

List Templates

Check Status

Modify Configuration

🐛 Troubleshooting

Common Issues

Error Messages

📖 API Reference

MCP Protocol Compliance

Response Format

Error Handling

🧪 Testing

🏗️ Development

Project Structure

Build and Run

Adding New Templates

Adding Language Support

🤝 Contributing

Development Workflow

📄 License

🙏 Acknowledgments

Related Servers

OTP MCP Server

Pickapicon

Figma to React Native MCP

EdgeOne Pages MCP

Grafana

MCP-ABI

MCP Terminal Server

refactor-mcp

WireMCP

Monad MCP Server

1. `generate_devcontainer`

2. `build_devcontainer`

3. `test_devcontainer`

4. `list_templates`

5. `modify_devcontainer`

6. `get_devcontainer_status`