Claude Code Docker MCP Server

Transform Claude Code into a Docker orchestration powerhouse with AI-driven containerization

🌟 What This Does

This MCP server enables Claude Code to:

• 🚀 Start/Stop Docker Environments: Launch isolated Claude Code containers on demand
• 🐳 Docker-in-Docker: Build and run containers inside Claude environments
• 📁 Workspace Management: Persistent file operations across container sessions
• 🔧 Command Execution: Run any command inside containerized environments
• 📊 Environment Monitoring: Real-time status and resource management

🚀 Quick Start

Installation

npm install -g @expertvagabond/claude-code-docker-mcp

Add to Claude Code

claude mcp add claude-docker npx @expertvagabond/claude-code-docker-mcp

Usage

# Start a development environment
claude "Start a new Claude Code environment with blockchain tools"

# Build and deploy an application
claude "Create a React app, containerize it, and run it on port 3000"

# Cross-chain development
claude "Start environment, build Solana NFT marketplace, deploy to testnet"

🛠️ Available Tools

Environment Management

• start_claude_environment: Launch new containerized environment
• stop_claude_environment: Stop and cleanup environment
• list_environments: Show all running environments
• get_environment_status: Detailed environment information

Development Operations

• execute_in_environment: Run commands inside containers
• build_docker_image: Build Docker images with AI-generated Dockerfiles
• run_container_in_environment: Deploy applications inside environments

Workspace Management

• workspace_file_operation: Read/write/list/delete workspace files

💡 Example Workflows

Full-Stack Development

claude "Start a development environment, create a MERN stack application with:
- React frontend with TypeScript
- Node.js Express API with MongoDB
- Docker compose configuration
- Build and start all services"

Blockchain Development

claude "Launch blockchain environment, create Solana program for NFT marketplace:
- Rust smart contract
- TypeScript SDK
- React frontend
- Deploy to devnet and test"

Microservices Architecture

claude "Create microservices environment with:
- User service (Node.js + PostgreSQL)
- Product service (Python + Redis)
- API Gateway (Nginx)
- Docker compose orchestration
- Build and start entire stack"

🔧 Configuration

Environment Variables

export CLAUDE_API_KEY="your-api-key"
export DOCKER_HOST="unix:///var/run/docker.sock"

Docker Requirements

• Docker Desktop installed and running
• 4GB+ RAM available for containers
• Docker BuildKit enabled (default in recent versions)

📋 Tool Reference

start_claude_environment

{
  name: "string",              // Environment name (default: claude-code-env)
  mode: "socket" | "dind",     // Docker mode (default: socket)
  workspace: "string",         // Host workspace path
  image: "string",             // Docker image (default: expertvagabond/claude-code-docker:latest)
  ports: ["3000:3000"]         // Port mappings
}

execute_in_environment

{
  name: "string",              // Environment name
  command: "string",           // Command to execute
  workdir: "string",           // Working directory (default: /workspace)
  user: "string"               // User (default: claude)
}

build_docker_image

{
  name: "string",              // Environment name
  dockerfile: "string",        // Dockerfile content or path
  tag: "string",               // Image tag
  context: "string"            // Build context (default: /workspace)
}

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│ Claude Code + MCP Server                                    │
│ ┌─────────────────┐    ┌─────────────────────────────────┐ │
│ │ Claude Code CLI │───▶│ Docker MCP Server               │ │
│ │                 │    │ - Environment Management       │ │
│ │ User Requests:  │    │ - Container Operations         │ │
│ │ "Start env"     │    │ - Workspace Management         │ │
│ │ "Build app"     │    │ - Docker-in-Docker Support     │ │
│ │ "Deploy"        │    └─────────────────────────────────┘ │
│ └─────────────────┘                     │                   │
└──────────────────────────────────────── │ ─────────────────┘
                                          │
                                          ▼
                    ┌─────────────────────────────────────────┐
                    │ Docker Engine                           │
                    │ ┌─────────────────────────────────────┐ │
                    │ │ Claude Code Container               │ │
                    │ │ ┌─────────────┐ ┌─────────────────┐ │ │
                    │ │ │ Claude Code │ │ Docker Engine   │ │ │
                    │ │ │ CLI         │ │ (Docker-in-Docker)│ │ │
                    │ │ └─────────────┘ └─────────────────┘ │ │
                    │ │ ┌─────────────────────────────────┐ │ │
                    │ │ │ Persistent Workspace            │ │ │
                    │ │ │ /workspace                      │ │ │
                    │ │ └─────────────────────────────────┘ │ │
                    │ └─────────────────────────────────────┘ │
                    └─────────────────────────────────────────┘

🔒 Security Features

• Isolated Environments: Each environment runs in its own container
• Non-root Execution: All commands run as claude user
• Workspace Sandboxing: File operations limited to workspace directory
• Network Isolation: Containers can be isolated from host network
• Resource Limits: CPU and memory limits can be configured

🚨 Troubleshooting

Common Issues

❌ "Cannot connect to Docker daemon"

# Ensure Docker Desktop is running
open -a Docker  # macOS
# or check Docker service on Linux
systemctl status docker

❌ "Permission denied"

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

❌ "Container startup fails"

# Check Docker logs
docker logs claude-code-env

# Check available resources
docker system df

❌ "MCP server not responding"

# Restart MCP server
claude mcp remove claude-docker
claude mcp add claude-docker npx @expertvagabond/claude-code-docker-mcp

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Make changes to the MCP server code
4. Test with: npm run build && npm start
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Setup

git clone https://github.com/ExpertVagabond/claude-code-docker.git
cd claude-code-docker/mcp-server
npm install
npm run build
npm run dev  # Watch mode

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Anthropic for Claude Code and MCP protocol
• Docker for containerization technology
• Node.js and TypeScript ecosystem

⭐ Star the repository if this helped you build better AI-powered applications!