MCP Server Automation CLI
About
A CLI tool to automate packaging MCP servers as Docker images and deploying them to AWS ECS.
Details
- Author
- aws-samples
- Categories
- Developer Tools, Other, Infrastructure
Jump to
Local Development Setup (MacOS or Linux)
# Clone and setup git clone https://github.com/aws-samples/sample-mcp-server-automation cd mcp-convert-automate uv sync source .venv/bin/activate # Run with config file uv run mcp-server-automation --config your-config.yaml # Run with direct command mode uv run mcp-server-automation -- npx -y @modelcontextprotocol/server-everything # Run with specific architecture uv run mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything
- Direct Command Mode: No configuration file needed - specify command directly with--separator
- Config File Mode: Use YAML configuration files for complex builds and deployments
Use the--separator to specify commands directly:
# Basic usage mcp-server-automation -- npx -y @modelcontextprotocol/server-everything # With ECR push (requires ECR repository to be configured separately) mcp-server-automation --push-to-ecr -- python -m my_server # With specific architecture for cross-platform builds mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything # Package name extraction for image naming # @modelcontextprotocol/server-everything → mcp-server-everything # mcp-server-automation → mcp-mcp-server-automation
- No config file required
- Automatic package name extraction for Docker image naming
- Multi-architecture support with--archparameter (linux/amd64, linux/arm64, etc.)
- Build-only mode (deployment requires config files)
- Simple--push-to-ecrflag support
For complex scenarios, use YAML configuration files withbuildanddeploysections:
build: # Method 1: Use command and package manager entrypoint: command: "npx" args: - "-y" - "@modelcontextprotocol/server-everything" # Method 2: Fetch MCP server from GitHub # github: # Required: GitHub repository URL for MCP server # github_url: "https://github.com/awslabs/mcp" # Optional: Subfolder path if MCP server is not in root # subfolder: "src/aws-documentation-mcp-server" # Optional: Git branch to build from (default: main) # branch: "develop" # Required for deployment: Must be true to enable ECR push and deployment push_to_ecr: true # Optional: Custom Docker image configuration # If not specified, auto-generated when push_to_ecr=true # image: # repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/mcp-servers/my-mcp-server" # tag: "v1.0" # Optional, defaults to dynamic git-based tag # Optional: AWS region (default: from AWS profile, fallback to us-east-1) # aws_region: "us-west-2" # Optional: Custom Dockerfile path # dockerfile_path: "./custom.Dockerfile" # Optional: Override auto-detected MCP server command # Required when README only contains Docker commands or no suitable command is found # command_override: # - "python" # - "-m" # - "my_server_module" # - "--verbose" # Optional: Set environment variables in the container # environment_variables: # LOG_LEVEL: "debug" # AWS_REGION: "us-east-1" # MCP_SERVER_NAME: "custom-server" # Optional: Target architecture for Docker build # architecture: "linux/arm64" # Options: linux/amd64, linux/arm64 deploy: # Required: Enable deployment (only works when push_to_ecr=true) enabled: true # Required: ECS service name service_name: "my-mcp-service" # Required: ECS cluster name cluster_name: "my-ecs-cluster" # Required: VPC ID where resources will be created vpc_id: "vpc-12345678" # Required: Subnet configuration alb_subnet_ids: # Public subnets for ALB (minimum 2 in different AZs) - "subnet-public-1" - "subnet-public-2" ecs_subnet_ids: # Private subnets for ECS tasks (minimum 1, should resides in AZ of alb_subnet_ids) - "subnet-private-1" - "subnet-private-2" # Optional: Container port (default: 8000) port: 8000 # Optional: Task CPU units (default: 256) cpu: 256 # Optional: Task memory in MB (default: 512) memory: 512 # Optional: SSL certificate ARN for HTTPS certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012" # Optional: Save MCP client configuration to file save_config: "./mcp-config.json"
build: github_url: "https://github.com/my-org/custom-mcp-server" dockerfile_path: "./custom/Dockerfile" push_to_ecr: true deploy: enabled: true # ... deployment configuration
Set custom environment variables that will be available to the MCP server at runtime:
build: github_url: "https://github.com/my-org/custom-mcp-server" environment_variables: LOG_LEVEL: "debug" AWS_REGION: "us-east-1" MCP_SERVER_NAME: "custom-server" PYTHONPATH: "/app/mcp-server:/custom/path" push_to_ecr: true
Set environment variables to override default AWS settings:
export AWS_REGION=us-west-2 export ECS_CLUSTER_NAME=my-production-cluster
- Command Parsing: Parses command and arguments from CLI using--separator (e.g.,-- npx -y @modelcontextprotocol/server-everything)
- Package Name Extraction: Automatically extracts package names for Docker image naming (e.g.,@modelcontextprotocol/server-everything→mcp-server-everything)
- Language Detection: Detects runtime (Node.js/Python) from command
- Dockerfile Generation: Creates optimized containers with pre-installed packages
- Image Building: Builds container ready to execute the specified command
- Repository Analysis: Downloads GitHub repos and detects MCP server configuration from README files (GitHub mode)
- Language Detection: Automatically detects Python or Node.js/TypeScript based on project files (package.json, pyproject.toml, etc.)
- Command Detection: Parses JSON blocks in README files to extract MCP server start commands from both Claude Desktop (mcpServers) and VS Code (mcp.servers) configuration formats
- Dockerfile Generation: Uses language-specific Jinja2 templates (Dockerfile-python.j2, Dockerfile-nodejs.j2) to create optimized builds with mcp-proxy CLI integration
- Image Building: Creates language-specific containers with proper dependency management and multi-stage builds
GitHub Repo → Docker Build → ECR → ECS Fargate ← ALB ← Internet ↓ ↓ ↓ ↓ ↓ MCP Server → mcp-proxy + MCP → Image → Service → HTTP/SSE Endpoints
The tool supports bothPythonandNode.js/TypeScriptMCP servers with automatic language detection:
- Detected by:pyproject.toml,requirements.txt,setup.py, or.pyfiles
- Package managers: pip, uv, poetry (automatically detected)
- Base image:python:3.12-slim-bookworm
- Command extraction from: console scripts in pyproject.toml, setup.py entry points
- Detected by:package.json,tsconfig.json, or.ts/.jsfiles
- Package manager: npm (with Node.js 24-bullseye base image)
- Base image:node:24-bullseye
- Command extraction from: README JSON configurations
The tool automatically detects MCP server startup commands from:
- README files- JSON configuration blocks supporting both formats:
- Claude Desktop:{"mcpServers": {...}}
- VS Code:{"mcp": {"servers": {...}}}
- README only contains Docker commands (not suitable for containerization)
- No suitable startup command can be detected
- You want to specify exact startup parameters
build: github: github_url: "https://github.com/my-org/custom-mcp-server" command_override: - "python" - "-m" - "my_server_module" - "--verbose" - "--port" - "3000" push_to_ecr: true
Example README Configurations Supported:
{ "mcpServers": { "everything": { "command": "npx", "args": ](https://github.com/punkpeye/mcp-proxy)["-y", "@modelcontextprotocol/server-everything"] } } }
{ "mcp": { "servers": { "everything": { "command": "python", "args": ["-m", "server"] } } } }
If your MCP server README only shows Docker commands:
{ "mcpServers": { "myserver": { "command": "docker", "args": ["run", "myserver:latest"] } } }
You'll get an error requiringcommand_overrideto specify the direct startup command.
- Ensure Docker daemon is running
- Check that the MCP server has proper dependency files (requirements.txt, pyproject.toml, etc.)
- Verify GitHub repository URL is accessible
When using the--archparameter orarchitecturein config files, you may encounter:
Error: "No builder available for architecture"
This means Docker Buildx is not properly configured. To fix:
# Create and use a new multi-platform builder docker buildx create --name multiarch --use # Or use an existing builder docker buildx use <builder-name> # List available builders docker buildx ls
- linux/amd64- Standard x86-64 (Intel/AMD)
- linux/arm64- ARM 64-bit (Apple Silicon, AWS Graviton)
For more information, visit:https://docs.docker.com/build/building/multi-platform/
- Ensure AWS credentials have ECR permissions
- Verify ECR repository exists and is accessible
- Check that Docker is authenticated with ECR
- Ensure AWS credentials have sufficient permissions
- Check that the ECS cluster exists
- Verify AWS region is correct
- Review CloudFormation events in AWS Console for detailed error messages
- Check container logs in local setup:docker logs <container-id>
- Verify health check endpoint:curl http://<alb-url>/mcp(expects HTTP 400)
- Test direct connection:curl http://<alb-url>/mcp
- Use debug mode for detailed logging
The AWS credentials used must have the following permissions:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "ecr:GetAuthorizationToken", "ecr:PutImage", "ecr:InitiateLayerUpload", "ecr:UploadLayerPart", "ecr:CompleteLayerUpload" ], "Resource": "" } ] }
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:", "cloudformation:", "ec2:", "elasticloadbalancing:", "iam:CreateRole", "iam:AttachRolePolicy", "iam:PassRole", "logs:CreateLogGroup", "logs:DescribeLogGroups" ], "Resource": "" } ] }
After deployment, the tool generates configuration for MCP clients:
{ "mcpServers": { "my-mcp-server": { "type": "sse", "url": "http://<ALB address>/sse" } } }
# Install mcp-proxy client npm install -g mcp-proxy # Test connection mcp-proxy https://your-alb-url.amazonaws.com/mcp
This library is licensed under the MIT-0 License. See the LICENSE file.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
A command-line tool to automate the deployment of MCP servers to AWS ECS.
Bult.ai MCP Server lets Claude Desktop deploy and manage Bult.ai cloud hosting resources, including projects, services, GitHub and Docker deployments, routes, volumes, templates, logs, and build history.
A guide and example code for deploying MCP servers cost-effectively on AWS and integrating them with AI agent frameworks.
A daemon to orchestrate MCP servers as Docker containers and configure AWS ALB path-based routing.
Access and interact with Harness platform data, including pipelines, repositories, logs, and artifact registries.
An SSE-based MCP server that allows LLM-powered applications to interact with OCI registries. It provides tools for retrieving information about container images, listing tags, and more.
The Railway MCP Server enables natural language interaction with your Railway projects and infrastructure. Ask your IDE or AI assistant to create projects, deploy templates, manage environments, pull variables, redeploy services, and more.
The Shipyard CLI provides an MCP server for agents to manage Shipyard environments directly: by pulling logs, comparing branches, running tests, and stopping/starting environments..
A server for automated provisioning, supporting both local and remote communication protocols.
Integrates with AWS CodePipeline to manage continuous integration and delivery pipelines.
A CLI tool to automate packaging MCP servers as Docker images and deploying them to AWS ECS.
A powerful CLI tool that automates the process of transforming Model Context Protocol (MCP) stdio servers into Docker images deployed on AWS ECS usingmcp-proxy. This tool bridges the gap between local MCP servers and remote HTTP-based deployments.
- ⚡ Direct Command Mode: Build MCP servers instantly without config files using--separator syntax
- 🔄 Automatic Build: Fetch MCP servers from GitHub, build Docker images, and push to ECR
- ☁️ One-Click Deploy: Generate CloudFormation templates and deploy complete ECS infrastructure
- 🔍 Smart Detection: Automatically detect MCP server commands from README files
- 🐳 Multi-Language: Support for Python and Node.js/TypeScript MCP servers with automatic language detection
- 🏷️ Smart Naming: Automatic package name extraction for Docker image naming
- 🔧 Debug Support: Built-in debug logging for troubleshooting
- 📝 Config Generation: Generate MCP client configurations for Claude Desktop, Cline, etc.
- Python 3.8+
- Docker(with daemon running)
- AWS CLIconfigured with appropriate permissions
- AWS ECR repository(created if using ECR push)
- AWS ECS cluster(created if deploying)
# On macOS and Linux. curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
The fastest way to build MCP server images is using direct command mode:
# Build MCP server image directly (no config file needed) uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation -- npx -y @modelcontextprotocol/server-everything # Build and push to ECR uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --push-to-ecr -- uvx mcp-server-automation # Build for specific architecture uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything
Use yaml-based config file with configuration files for complex deployments:
# Install from a Git repository uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --config your-config.yaml
Local Development Setup (MacOS or Linux)
# Clone and setup git clone https://github.com/aws-samples/sample-mcp-server-automation cd mcp-convert-automate uv sync source .venv/bin/activate # Run with config file uv run mcp-server-automation --config your-config.yaml # Run with direct command mode uv run mcp-server-automation -- npx -y @modelcontextprotocol/server-everything # Run with specific architecture uv run mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything
- Direct Command Mode: No configuration file needed - specify command directly with--separator
- Config File Mode: Use YAML configuration files for complex builds and deployments
Use the--separator to specify commands directly:
# Basic usage mcp-server-automation -- npx -y @modelcontextprotocol/server-everything # With ECR push (requires ECR repository to be configured separately) mcp-server-automation --push-to-ecr -- python -m my_server # With specific architecture for cross-platform builds mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything # Package name extraction for image naming # @modelcontextprotocol/server-everything → mcp-server-everything # mcp-server-automation → mcp-mcp-server-automation
- No config file required
- Automatic package name extraction for Docker image naming
- Multi-architecture support with--archparameter (linux/amd64, linux/arm64, etc.)
- Build-only mode (deployment requires config files)
- Simple--push-to-ecrflag support
For complex scenarios, use YAML configuration files withbuildanddeploysections:
build: # Method 1: Use command and package manager entrypoint: command: "npx" args: - "-y" - "@modelcontextprotocol/server-everything" # Method 2: Fetch MCP server from GitHub # github: # Required: GitHub repository URL for MCP server # github_url: "https://github.com/awslabs/mcp" # Optional: Subfolder path if MCP server is not in root # subfolder: "src/aws-documentation-mcp-server" # Optional: Git branch to build from (default: main) # branch: "develop" # Required for deployment: Must be true to enable ECR push and deployment push_to_ecr: true # Optional: Custom Docker image configuration # If not specified, auto-generated when push_to_ecr=true # image: # repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/mcp-servers/my-mcp-server" # tag: "v1.0" # Optional, defaults to dynamic git-based tag # Optional: AWS region (default: from AWS profile, fallback to us-east-1) # aws_region: "us-west-2" # Optional: Custom Dockerfile path # dockerfile_path: "./custom.Dockerfile" # Optional: Override auto-detected MCP server command # Required when README only contains Docker commands or no suitable command is found # command_override: # - "python" # - "-m" # - "my_server_module" # - "--verbose" # Optional: Set environment variables in the container # environment_variables: # LOG_LEVEL: "debug" # AWS_REGION: "us-east-1" # MCP_SERVER_NAME: "custom-server" # Optional: Target architecture for Docker build # architecture: "linux/arm64" # Options: linux/amd64, linux/arm64 deploy: # Required: Enable deployment (only works when push_to_ecr=true) enabled: true # Required: ECS service name service_name: "my-mcp-service" # Required: ECS cluster name cluster_name: "my-ecs-cluster" # Required: VPC ID where resources will be created vpc_id: "vpc-12345678" # Required: Subnet configuration alb_subnet_ids: # Public subnets for ALB (minimum 2 in different AZs) - "subnet-public-1" - "subnet-public-2" ecs_subnet_ids: # Private subnets for ECS tasks (minimum 1, should resides in AZ of alb_subnet_ids) - "subnet-private-1" - "subnet-private-2" # Optional: Container port (default: 8000) port: 8000 # Optional: Task CPU units (default: 256) cpu: 256 # Optional: Task memory in MB (default: 512) memory: 512 # Optional: SSL certificate ARN for HTTPS certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012" # Optional: Save MCP client configuration to file save_config: "./mcp-config.json"
build: github_url: "https://github.com/my-org/custom-mcp-server" dockerfile_path: "./custom/Dockerfile" push_to_ecr: true deploy: enabled: true # ... deployment configuration
Set custom environment variables that will be available to the MCP server at runtime:
build: github_url: "https://github.com/my-org/custom-mcp-server" environment_variables: LOG_LEVEL: "debug" AWS_REGION: "us-east-1" MCP_SERVER_NAME: "custom-server" PYTHONPATH: "/app/mcp-server:/custom/path" push_to_ecr: true
Set environment variables to override default AWS settings:
export AWS_REGION=us-west-2 export ECS_CLUSTER_NAME=my-production-cluster
- Command Parsing: Parses command and arguments from CLI using--separator (e.g.,-- npx -y @modelcontextprotocol/server-everything)
- Package Name Extraction: Automatically extracts package names for Docker image naming (e.g.,@modelcontextprotocol/server-everything→mcp-server-everything)
- Language Detection: Detects runtime (Node.js/Python) from command
- Dockerfile Generation: Creates optimized containers with pre-installed packages
- Image Building: Builds container ready to execute the specified command
- Repository Analysis: Downloads GitHub repos and detects MCP server configuration from README files (GitHub mode)
- Language Detection: Automatically detects Python or Node.js/TypeScript based on project files (package.json, pyproject.toml, etc.)
- Command Detection: Parses JSON blocks in README files to extract MCP server start commands from both Claude Desktop (mcpServers) and VS Code (mcp.servers) configuration formats
- Dockerfile Generation: Uses language-specific Jinja2 templates (Dockerfile-python.j2, Dockerfile-nodejs.j2) to create optimized builds with mcp-proxy CLI integration
- Image Building: Creates language-specific containers with proper dependency management and multi-stage builds
GitHub Repo → Docker Build → ECR → ECS Fargate ← ALB ← Internet ↓ ↓ ↓ ↓ ↓ MCP Server → mcp-proxy + MCP → Image → Service → HTTP/SSE Endpoints
The tool supports bothPythonandNode.js/TypeScriptMCP servers with automatic language detection:
- Detected by:pyproject.toml,requirements.txt,setup.py, or.pyfiles
- Package managers: pip, uv, poetry (automatically detected)
- Base image:python:3.12-slim-bookworm
- Command extraction from: console scripts in pyproject.toml, setup.py entry points
- Detected by:package.json,tsconfig.json, or.ts/.jsfiles
- Package manager: npm (with Node.js 24-bullseye base image)
- Base image:node:24-bullseye
- Command extraction from: README JSON configurations
The tool automatically detects MCP server startup commands from:
- README files- JSON configuration blocks supporting both formats:
- Claude Desktop:{"mcpServers": {...}}
- VS Code:{"mcp": {"servers": {...}}}
- README only contains Docker commands (not suitable for containerization)
- No suitable startup command can be detected
- You want to specify exact startup parameters
build: github: github_url: "https://github.com/my-org/custom-mcp-server" command_override: - "python" - "-m" - "my_server_module" - "--verbose" - "--port" - "3000" push_to_ecr: true
Example README Configurations Supported:
{ "mcpServers": { "everything": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"] } } }
{ "mcp": { "servers": { "everything": { "command": "python", "args": ["-m", "server"] } } } }
If your MCP server README only shows Docker commands:
{ "mcpServers": { "myserver": { "command": "docker", "args": ["run", "myserver:latest"] } } }
You'll get an error requiringcommand_overrideto specify the direct startup command.
- Ensure Docker daemon is running
- Check that the MCP server has proper dependency files (requirements.txt, pyproject.toml, etc.)
- Verify GitHub repository URL is accessible
When using the--archparameter orarchitecturein config files, you may encounter:
Error: "No builder available for architecture"
This means Docker Buildx is not properly configured. To fix:
# Create and use a new multi-platform builder docker buildx create --name multiarch --use # Or use an existing builder docker buildx use <builder-name> # List available builders docker buildx ls
- linux/amd64- Standard x86-64 (Intel/AMD)
- linux/arm64- ARM 64-bit (Apple Silicon, AWS Graviton)
For more information, visit:https://docs.docker.com/build/building/multi-platform/
- Ensure AWS credentials have ECR permissions
- Verify ECR repository exists and is accessible
- Check that Docker is authenticated with ECR
- Ensure AWS credentials have sufficient permissions
- Check that the ECS cluster exists
- Verify AWS region is correct
- Review CloudFormation events in AWS Console for detailed error messages
- Check container logs in local setup:docker logs <container-id>
- Verify health check endpoint:curl http://<alb-url>/mcp(expects HTTP 400)
- Test direct connection:curl http://<alb-url>/mcp
- Use debug mode for detailed logging
The AWS credentials used must have the following permissions:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "ecr:GetAuthorizationToken", "ecr:PutImage", "ecr:InitiateLayerUpload", "ecr:UploadLayerPart", "ecr:CompleteLayerUpload" ], "Resource": "" } ] }
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:", "cloudformation:", "ec2:", "elasticloadbalancing:", "iam:CreateRole", "iam:AttachRolePolicy", "iam:PassRole", "logs:CreateLogGroup", "logs:DescribeLogGroups" ], "Resource": "" } ] }
After deployment, the tool generates configuration for MCP clients:
{ "mcpServers": { "my-mcp-server": { "type": "sse", "url": "http://<ALB address>/sse" } } }
# Install mcp-proxy client npm install -g mcp-proxy # Test connection mcp-proxy https://your-alb-url.amazonaws.com/mcp
This library is licensed under the MIT-0 License. See the LICENSE file.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
A command-line tool to automate the deployment of MCP servers to AWS ECS.
Bult.ai MCP Server lets Claude Desktop deploy and manage Bult.ai cloud hosting resources, including projects, services, GitHub and Docker deployments, routes, volumes, templates, logs, and build history.
A guide and example code for deploying MCP servers cost-effectively on AWS and integrating them with AI agent frameworks.
A daemon to orchestrate MCP servers as Docker containers and configure AWS ALB path-based routing.
Access and interact with Harness platform data, including pipelines, repositories, logs, and artifact registries.
An SSE-based MCP server that allows LLM-powered applications to interact with OCI registries. It provides tools for retrieving information about container images, listing tags, and more.
The Railway MCP Server enables natural language interaction with your Railway projects and infrastructure. Ask your IDE or AI assistant to create projects, deploy templates, manage environments, pull variables, redeploy services, and more.
The Shipyard CLI provides an MCP server for agents to manage Shipyard environments directly: by pulling logs, comparing branches, running tests, and stopping/starting environments..
A server for automated provisioning, supporting both local and remote communication protocols.
Integrates with AWS CodePipeline to manage continuous integration and delivery pipelines.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
