How do I install Containerization Assist?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Containerization Assist need an API key?

The publisher lists these environment variables: DOCKER_SOCKET, LOG_LEVEL.

What transport does Containerization Assist use?

Containerization Assist runs locally over stdio.

When was Containerization Assist last checked?

Last checked 2026-11-08. TypeScript MCP server for AI-powered containerization workflows with Docker and Kubernetes support

Containerization Assist MCP server

Containerization Assist MCP Server

An AI-powered containerization assistant that helps you build, scan, and deploy Docker containers through VS Code and other MCP-compatible tools.

Full documentation →

Install

Features

Core Capabilities

🐳 Docker Integration: Build, scan, and deploy container images
☸️ Kubernetes Support: Generate manifests and deploy applications
🤖 AI-Powered: Intelligent Dockerfile generation and optimization
🧠 Knowledge Enhanced: AI-driven content improvement with security and performance best practices
🔄 Intelligent Tool Routing: Automatic dependency resolution and execution
📊 Progress Tracking: Real-time progress updates via MCP notifications
🔒 Security Scanning: Built-in vulnerability scanning with AI-powered suggestions
✨ Smart Analysis: Context-aware recommendations
Policy-Driven System (v3.0)
- Pre-generation configuration
- Knowledge filtering and weighting
- Template injection
- Semantic validation
- Cross-tool consistency

Policy System (v3.0)

Full control over containerization through Rego policies:

Configure Before Generation: Set defaults for resources, base images, build strategy
Guide During Generation: Filter knowledge base, inject templates automatically
Validate After Generation: Semantic checks, security scoring, cross-tool consistency

Example Policies Included:

Environment-based strategy (dev/staging/prod)
Cost control by team tier
Security-first organization
Multi-cloud registry governance
Speed-optimized development

See Policy Authoring Guide for details.

System Requirements

Node.js 20+
Docker or Docker Desktop
Optional: Trivy (for security scanning features)
Optional: Kubernetes (for deployment features)

Manual Install

Add the following to your VS Code settings or create .vscode/mcp.json in your project:

{
  "servers": {
    "ca": {
      "command": "npx",
      "args": ["-y", "containerization-assist-mcp", "start"],
      "env": {
         "LOG_LEVEL": "info"
      }
    }
  }
}

Restart VS Code to enable the MCP server in GitHub Copilot.

SDK Usage (Without MCP)

For direct tool usage without MCP protocol (e.g., VS Code extensions, programmatic access):

import { analyzeRepo, buildImageContext, scanImage } from 'containerization-assist-mcp/sdk';
import { execSync } from 'child_process';

// Simple function calls - no MCP server needed
const analysis = await analyzeRepo({ repositoryPath: './myapp' });
if (analysis.ok) {
  console.log('Detected:', analysis.value.modules);
}

// buildImageContext returns build context with security analysis and commands
const buildContext = await buildImageContext({ path: './myapp', imageName: 'myapp:v1', platform: 'linux/amd64' });
if (buildContext.ok) {
  const { securityAnalysis, nextAction } = buildContext.value;
  console.log('Security risk:', securityAnalysis.riskLevel);
  
  // Execute the generated build command from the build context directory
  execSync(nextAction.buildCommand.command, {
    cwd: buildContext.value.context.buildContextPath,
    env: { ...process.env, ...nextAction.buildCommand.environment }
  });
}

const scan = await scanImage({ imageId: 'myapp:v1' });

See the SDK integration examples for full SDK documentation.

Windows Users

For Windows, use the Windows Docker pipe:

"DOCKER_SOCKET": "//./pipe/docker_engine"

Quick Start

The easiest way to understand the containerization workflow is through an end-to-end example:

Single-App Containerization Journey

This MCP server guides you through a complete containerization workflow for a single application. The journey follows this sequence:

Analyze Repository → Understand your application's language, framework, and dependencies
Generate Dockerfile → Create an optimized, security-hardened container configuration
Build Image → Compile your application into a Docker image
Scan Image → Identify security vulnerabilities and get remediation guidance
Tag Image → Apply appropriate version tags to your image
Generate K8s Manifests → Create deployment configurations for Kubernetes
Prepare Cluster → Set up namespace and prerequisites, then deploy with kubectl apply
Verify → Confirm deployment health and readiness

Prerequisites

Before starting, ensure you have:

Docker: Running Docker daemon with accessible socket (docker ps should work)
- Linux/Mac: /var/run/docker.sock accessible
- Windows: Docker Desktop with //./pipe/docker_engine accessible
Kubernetes (optional, for deployment features):
- Valid kubeconfig at ~/.kube/config
- Cluster connectivity (kubectl cluster-info should work)
- Appropriate RBAC permissions for deployments, services, namespaces
Node.js: Version 20 or higher
MCP Client: VS Code with Copilot, Claude Desktop, or another MCP-compatible client

Example Workflow with Natural Language

Once configured in your MCP client (VS Code Copilot, Claude Desktop, etc.), use natural language:

Starting the Journey:

"Analyze my Java application for containerization"

Building the Container:

"Generate an optimized Dockerfile with security best practices"
"Build a Docker image tagged myapp:v1.0.0"
"Scan the image for vulnerabilities"

Deploying to Kubernetes:

"Generate Kubernetes manifests for this application"
"Prepare my cluster and deploy to the default namespace"
"Verify the deployment is healthy"

Single-Operator Model

This server is optimized for one engineer containerizing one application at a time. Key characteristics:

Sequential execution: Each tool builds on the results of previous steps
Fast-fail validation: Clear, actionable error messages if Docker/Kubernetes are unavailable
Deterministic AI generation: Tools provide reproducible outputs through built-in prompt engineering
Real-time progress: MCP notifications surface progress updates to clients during long-running operations

Multi-Module/Monorepo Support

The server detects and supports monorepo structures with multiple independently deployable services:

Automatic Detection: analyze-repo identifies monorepo patterns (npm workspaces, services/, apps/ directories)
Automated Multi-Module Generation: generate-dockerfile and generate-k8s-manifests support multi-module workflows
Conservative Safeguards: Excludes shared libraries and utility folders from containerization

Multi-Module Workflow Example:

1. "Analyze my monorepo at ./my-monorepo"
   → Detects 3 modules: api-gateway, user-service, notification-service

2. "Generate Dockerfiles"
   → Automatically creates Dockerfiles for all 3 modules:
     - services/api-gateway/Dockerfile
     - services/user-service/Dockerfile
     - services/notification-service/Dockerfile

3. "Generate K8s manifests"
   → Automatically creates manifests for all 3 modules

4. Optional: "Generate Dockerfile for user-service module"
   → Creates module-specific deployment manifests

Detection Criteria:

Workspace configurations (npm, yarn, pnpm workspaces, lerna, nx, turborepo, cargo workspace)
Separate package.json, pom.xml, go.mod, Cargo.toml per service
Independent entry points and build configs
EXCLUDES: shared/, common/, lib/, packages/utils directories

Available Tools

The server provides 11 MCP tools organized by functionality:

Analysis & Planning

Tool	Description
`analyze-repo`	Analyze repository structure and detect technologies by parsing config files

Dockerfile Operations

Tool	Description
`generate-dockerfile`	Gather insights from knowledge base and return requirements for Dockerfile creation
`fix-dockerfile`	Analyze Dockerfile for issues including organizational policy validation and return knowledge-based fix recommendations

Image Operations

Tool	Description
`build-image-context`	Prepare Docker build context with security analysis and return build commands
`scan-image`	Scan Docker images for security vulnerabilities with remediation guidance (uses Trivy CLI)
`tag-image`	Tag Docker images with version and registry information
`push-image`	Push Docker images to a registry

Kubernetes Operations

Tool	Description
`generate-k8s-manifests`	Gather insights and return requirements for Kubernetes/Helm/ACA/Kustomize manifest creation
`prepare-cluster`	Prepare Kubernetes cluster for deployment
`verify-deploy`	Verify Kubernetes deployment status

Utilities

Tool	Description
`ops`	Operational utilities for ping and server status

Workflow Tools

Interactive workflow tools that return step-by-step plans (output is collapsed by default in VS Code Copilot Chat):

Tool	Description	Inputs
`create-containerization-policy`	Step-by-step guidance for authoring a custom OPA Rego policy	None
`kind-loop`	Local dev loop: analyze → build → scan → deploy to Kind	`namespace` (optional), `imageName` (optional)
`aks-loop`	Remote dev loop: analyze → build → push → deploy to AKS	`registry`, `resourceGroup`, `clusterName` (required); `namespace`, `imageName` (optional)

Version Tracking

All generated artifacts include version metadata so you can track which version of containerization-assist produced them.

Dockerfiles (generate-dockerfile):

The tool output includes attributionLabels.labels with a version label, included as a LABEL instruction in the generated Dockerfile:

Label	Value	Purpose
`com.azure.containerizationassist.version`	Package version (e.g., `1.4.0`)	Version of containerization-assist used

Kubernetes Manifests (generate-k8s-manifests):

The tool output includes attributionLabels.annotations applied to all generated Kubernetes resource metadata:

Type	Key	Value	Purpose
Annotation	`com.azure.containerizationassist/version`	Package version (e.g., `1.4.0`)	Version of containerization-assist used

Organizations can add custom labels via the policy system's orgStandards.requiredLabels configuration.

Supported Technologies

Languages & Frameworks

Java: Spring Boot, Quarkus, Micronaut (Java 8-21)
.NET: ASP.NET Core, Blazor (.NET 6.0+)

Build Systems

Maven, Gradle (Java)
dotnet CLI (.NET)

Configuration

Environment Variables

The following environment variables control server behavior:

Variable	Description	Default	Required
`DOCKER_SOCKET`	Docker socket path	`/var/run/docker.sock` (Linux/Mac)`//./pipe/docker_engine` (Windows)	No
`DOCKER_HOST`	Docker host URI (`unix://`, `tcp://`, `http://`, `https://`, `npipe://`)	Auto-detected	No
`DOCKER_TIMEOUT`	Docker operation timeout in milliseconds	`60000` (60s)	No
`KUBECONFIG`	Path to Kubernetes config file	`~/.kube/config`	No
`K8S_NAMESPACE`	Default Kubernetes namespace	`default`	No
`LOG_LEVEL`	Logging level	`info`	No
`WORKSPACE_DIR`	Working directory for operations	Current directory	No
`MCP_MODE`	Enable MCP protocol mode (logs to stderr)	`false`	No
`MCP_QUIET`	Suppress non-essential output in MCP mode	`false`	No
`CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH`	Directory path for tool execution logs (JSON format)	Disabled	No
`CUSTOM_POLICY_PATH`	Directory path for custom policies (highest priority)	Not set	No

Progress Notifications: Long-running operations (build, deploy, scan-image) emit real-time progress updates via MCP notifications. MCP clients can subscribe to these notifications to display progress to users.

Tool Execution Logging

Enable detailed logging of all tool executions to JSON files for debugging and auditing:

export CONTAINERIZATION_ASSIST_TOOL_LOGS_DIR_PATH=/path/to/logs

Log File Format:

Filename: ca-tool-logs-${timestamp}.jsonl
Example: ca-tool-logs-2025-10-13T14-30-15-123Z.jsonl

Log Contents:

{
  "timestamp": "2025-10-13T14:30:15.123Z",
  "toolName": "analyze-repo",
  "input": { "path": "/workspace/myapp" },
  "output": { "language": "typescript", "framework": "express" },
  "success": true,
  "durationMs": 245,
  "error": "Error message if failed",
  "errorGuidance": {
    "hint": "Suggested fix",
    "resolution": "Step-by-step instructions"
  }
}

The logging directory is validated at startup to ensure it's writable.

Policy System

The policy system uses OPA Rego for security, quality, and compliance enforcement. Rego is the industry-standard policy language from Open Policy Agent, providing expressive rules with rich built-in functions.

Default Behavior (No Configuration Needed): By default, all policies in the policies/ directory are automatically discovered and merged:

policies/security-baseline.rego - Essential security rules (root user prevention, secrets detection, privileged containers)
policies/base-images.rego - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)
policies/container-best-practices.rego - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)

This provides comprehensive out-of-the-box security and quality enforcement.

Policy Customization

The policy system supports four priority-ordered search paths for easy customization:

Priority Order (highest to lowest):

Custom directory via CUSTOM_POLICY_PATH environment variable (highest priority)
Project directory at <git-root>/.containerization-assist/policy/ (tracked in git)
Global directory at ~/.config/containerization-assist/policy/ (XDG-compliant)
Built-in policies/ (shipped with package, lowest priority)

Migration Note: The policies.user/ directory is deprecated. For project-specific policies, use .containerization-assist/policy/ at your git root. For user-wide policies, use ~/.config/containerization-assist/policy/. The old directory still works but will log a deprecation warning.

Quick Start

# Option 1: Global policies (no env var needed)
mkdir -p ~/.config/containerization-assist/policy

# Copy example policy from the npm package
cp node_modules/containerization-assist-mcp/policies.user.examples/allow-all-registries.rego \
   ~/.config/containerization-assist/policy/

# Policies are auto-reloaded on the next tool execution — no restart needed

Or set a custom location in .vscode/mcp.json:

{
  "servers": {
    "ca": {
      "env": {
        "CUSTOM_POLICY_PATH": "/path/to/policies"
      }
    }
  }
}

Pre-Built Example Policies

The policies.user.examples/ directory (included in the npm package) provides three ready-to-use examples:

Example	Purpose	Use Case
`allow-all-registries.rego`	Override MCR preference	Docker Hub, GCR, ECR, private registries
`warn-only-mode.rego`	Advisory-only enforcement	Testing, gradual adoption, dev environments
`custom-organization-template.rego`	Organization template	Custom labels, registries, compliance

See policies.user.examples/README.md for detailed usage.

Built-In Policies

Three production-ready Rego policies are included by default:

policies/security-baseline.rego - Essential security rules (root user prevention, secrets detection, privileged containers)
policies/base-images.rego - Base image governance (Microsoft Azure Linux recommendation, no :latest tag, deprecated versions)
policies/container-best-practices.rego - Docker best practices (HEALTHCHECK, multi-stage builds, layer optimization)

User policies override built-in policies by package namespace.

Policy File Format (Rego):

package containerization.custom_policy

# Blocking violations
violations contains result if {
  input_type == "dockerfile"
  regex.match(`FROM\s+[^:]+:latest`, input.content)

  result := {
    "rule": "block-latest-tag",
    "category": "quality",
    "priority": 80,
    "severity": "block",
    "message": "Using :latest tag is not allowed. Specify explicit version tags.",
    "description": "Prevent :latest for reproducibility",
  }
}

# Non-blocking warnings
warnings contains result if {
  input_type == "dockerfile"
  not regex.match(`HEALTHCHECK`, input.content)

  result := {
    "rule": "suggest-healthcheck",
    "category": "quality",
    "priority": 70,
    "severity": "warn",
    "message": "Consider adding HEALTHCHECK instruction for container monitoring",
    "description": "HEALTHCHECK improves container lifecycle management",
  }
}

# Policy decision
default allow := false
allow if count(violations) == 0

# Result structure
result := {
  "allow": allow,
  "violations": violations,
  "warnings": warnings,
  "suggestions": [],
  "summary": {
    "total_violations": count(violations),
    "total_warnings": count(warnings),
    "total_suggestions": 0,
  },
}

Priority Levels:

90-100: Security rules (highest priority)
70-89: Quality rules
50-69: Performance rules
30-49: Compliance rules

Using Policies:

# List discovered policies
npx containerization-assist-mcp list-policies

# List policies and show merged result
npx containerization-assist-mcp list-policies --show-merged

# Validate Dockerfile with policies (automatic discovery)
npx containerization-assist-mcp fix-dockerfile --path ./Dockerfile

Creating Custom Policies:

See Policy Customization Guide and existing policies in policies/ for examples.

Testing Policies:

# Validate policy syntax
opa check .containerization-assist/policy/my-policy.rego

# Run policy tests
opa test .containerization-assist/policy/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector containerization-assist-mcp start

MCP Inspector (Testing)

npx @modelcontextprotocol/inspector containerization-assist-mcp start

Troubleshooting

Docker Connection Issues

# Check Docker is running
docker ps

# Check socket permissions (Linux/Mac)
ls -la /var/run/docker.sock

# For Windows, ensure Docker Desktop is running

MCP Connection Issues

# Test with MCP Inspector
npx @modelcontextprotocol/inspector containerization-assist-mcp start

# Check logs with debug level
npx -y containerization-assist-mcp start --log-level debug

Kubernetes Connection Issues

The server performs fast-fail validation when Kubernetes tools are used. If you encounter Kubernetes errors:

Kubeconfig Not Found

# Check if kubeconfig exists
ls -la ~/.kube/config

# Verify kubectl can connect
kubectl cluster-info

# If using cloud providers, update kubeconfig:
# AWS EKS
aws eks update-kubeconfig --name <cluster-name> --region <region>

# Google GKE
gcloud container clusters get-credentials <cluster-name> --zone <zone>

# Azure AKS
az aks get-credentials --resource-group <rg> --name <cluster-name>

Connection Timeout or Refused

# Verify cluster is running
kubectl get nodes

# Check API server address
kubectl config view

# Test connectivity to API server
kubectl cluster-info dump

# Verify firewall rules allow connection to API server port (typically 6443)

Authentication or Authorization Errors

# Check current context and user
kubectl config current-context
kubectl config view --minify

# Test permissions
kubectl auth can-i create deployments --namespace default
kubectl auth can-i create services --namespace default

# If using cloud providers, refresh credentials:
# AWS EKS: re-run update-kubeconfig
# GKE: run gcloud auth login
# AKS: run az login

Invalid or Missing Context

# List available contexts
kubectl config get-contexts

# Set a context
kubectl config use-context <context-name>

# View current configuration
kubectl config view

License

MIT License - See LICENSE file for details.

Support

See SUPPORT.md for information on how to get help with this project.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Containerization Assist?

Does Containerization Assist need an API key?

What transport does Containerization Assist use?

When was Containerization Assist last checked?

Documentation

Containerization Assist MCP Server

Install

Features

Core Capabilities

Policy System (v3.0)

System Requirements

Manual Install

SDK Usage (Without MCP)

Windows Users

Quick Start

Single-App Containerization Journey

Prerequisites

Example Workflow with Natural Language

Single-Operator Model

Multi-Module/Monorepo Support

Available Tools

Analysis & Planning

Dockerfile Operations

Image Operations

Kubernetes Operations

Utilities

Workflow Tools

Version Tracking

Supported Technologies

Languages & Frameworks

Build Systems

Configuration

Environment Variables

Tool Execution Logging

Policy System

Policy Customization

Quick Start

Pre-Built Example Policies

Built-In Policies

MCP Inspector (Testing)

Troubleshooting

Docker Connection Issues

MCP Connection Issues

Kubernetes Connection Issues

License

Support

Trademarks