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.

Related MCP server: Advanced MCP Server

Supported Stacks

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

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.