DevEnv MCP Server

An MCP (Model Context Protocol) server that provisions Docker-based development environments on demand.

Any AI agent (Claude, Gemini, Cursor, etc.) can call these tools to create, manage, and inspect containerized dev environments — completely hands-free. No more manual setup of Node, Python, or Docker Compose for every new project.

Features

• Instant Scaffolding: Create full-stack projects (Next.js, Flask, FastAPI, etc.) with one command.
• Docker Isolation: Every environment runs in its own container, keeping your host machine clean.
• Two Workspace Modes: isolated (default, container-only files) or mapped (bind-mounted host files).
• Hands-free Dependencies: The AI automatically installs required packages and sets up the environment.
• Direct File Access: write_file and read_file tools let the agent modify files inside the container.
• Portable Export: export_environment snapshots an environment into a Docker image tarball.
• Universal IDE Support: Works with VS Code (Gemini), Claude Desktop, Cursor, Windsurf, and Claude CLI.

Supported Stacks

Stack	Framework	Base Image	Default Port
flask	Flask (Python)	python:3.12-slim	5000
django	Django (Python)	python:3.12-slim	8000
fastapi	FastAPI (Python)	python:3.12-slim	8000
nextjs	Next.js (React)	node:20-slim	3000
vite-react	Vite + React	node:20-slim	5173
vite-vue	Vite + Vue	node:20-slim	5173
express	Express.js	node:20-slim	3000
static-html	Static HTML/CSS/JS	node:20-slim	8080
laravel	Laravel (PHP)	php:8.3-fpm-alpine	8000
symfony	Symfony (PHP)	php:8.3-fpm-alpine	8000
nestjs	NestJS (Node.js)	node:22-slim	3000
bun-hono	Hono (Bun)	oven/bun:1-alpine	3000
rust-axum	Axum/Actix (Rust)	rust:1-slim	8080
go-gin	Gin/Fiber (Go)	golang:1.24-alpine	8080
nginx-static	Nginx (Static Assets)	nginx:alpine	80

Prerequisites

• Docker with docker compose v2 installed and running.
• Python 3.10+ with pip.

Quick Start

1. Clone and Install:

   git clone https://github.com/ClaudiuJitea/devenv-mcp-server.git
   cd devenv-mcp-server
   pip install -r requirements.txt
   

2. Configure your IDE: (See IDE Integration below)

3. Start Creating: Ask your AI agent:

   "Create a new Next.js project called 'my-portfolio' using the devenv tool."

IDE Integration

Gemini Code Assist (VS Code)

Add to your VS Code settings.json:

{
  "gemini.mcp.servers": {
    "devenv": {
      "command": "python3",
      "args": ["/absolute/path/to/server.py"],
      "env": {}
    }
  }
}

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "devenv": {
      "command": "python3",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Cursor / Windsurf / Claude CLI

The server supports the standard MCP protocol via stdio. Use the path to server.py in your configuration.

Available Tools

Tool	Description
list_supported_stacks	Show all available technology stacks
create_environment	Create a new Docker dev environment
list_environments	List all environments and their status
start_environment	Start a stopped environment
stop_environment	Stop a running environment
destroy_environment	Remove environment, container, volumes, associated images, and files by default
exec_command	Run a command inside a container
write_file	Write/create a file inside a container's /app
read_file	Read a file from a container's /app
get_environment_info	Get detailed environment info
export_environment	Export a portable image tar and generate deploy scripts

Workspace Modes

create_environment supports workspace_mode:

• isolated (default): no host bind mount. Source code, dependencies, and generated files stay inside the container.
• mapped: bind-mount project files from ~/devenv-projects/<project> to /app for direct host editing.

Recommended default is isolated when you want portability and host isolation.

How It Works

1. Request: The AI agent identifies a stack requirement (e.g., "I want a Flask app").
2. Execution: It calls create_environment(project_name="app", stack="flask", workspace_mode="isolated").
3. Provisioning: The MCP server:
   • Creates a project directory at ~/devenv-projects/<project>/.
   • Generates Dockerfile, compose, and metadata files.
   • Builds and starts a dedicated container for that project.
   • Runs stack-specific initialization commands when required.
4. Editing Workflow:
   • In isolated mode, use write_file, read_file, and exec_command to work entirely in-container.
   • In mapped mode, edit files directly from the host and they reflect in the container.
5. Portability: Call export_environment to snapshot and save a tarball (docker load -i ... on another machine). In mapped mode, export automatically captures mapped host files into an isolated image first. The export also writes deploy-<project>.sh and deploy-<project>.ps1 next to the tar.

Directory Structure

~/devenv-projects/
└── my-project/
    ├── Dockerfile
    ├── docker-compose.yml
    ├── .devenv.json
    ├── app.py            # or stack scaffold files
    └── ...

Development

To test the server manually:

python3 server.py

Or use the MCP Inspector:

npx @modelcontextprotocol/inspector python3 server.py

---

Built for the AI-First Developer Workflow.