MCP Server Automation CLI

Una herramienta de línea de comandos para automatizar el empaquetado de servidores MCP como imágenes Docker y su despliegue en AWS ECS.

GitHub
4
Prueba este MCPPatrocinado

Documentación

MCP Server Automation CLI

Una potente herramienta CLI que automatiza el proceso de transformar servidores MCP (Model Context Protocol) stdio en imágenes Docker desplegadas en AWS ECS usando mcp-proxy. Esta herramienta cierra la brecha entre servidores MCP locales y despliegues remotos basados en HTTP.

🚀 Características

  • ⚡ Modo de Comando Directo: Construye servidores MCP al instante sin archivos de configuración usando la sintaxis de separador --
  • 🔄 Construcción Automática: Obtiene servidores MCP desde GitHub, construye imágenes Docker y las sube a ECR
  • ☁️ Despliegue con Un Clic: Genera plantillas CloudFormation y despliega infraestructura ECS completa
  • 🔍 Detección Inteligente: Detecta automáticamente los comandos del servidor MCP desde archivos README
  • 🐳 Multi-Lenguaje: Soporte para servidores MCP de Python y Node.js/TypeScript con detección automática de lenguaje
  • 🏷️ Nombrado Inteligente: Extracción automática del nombre del paquete para el nombrado de imágenes Docker
  • 🔧 Soporte de Depuración: Registro de depuración integrado para solucionar problemas
  • 📝 Generación de Configuración: Genera configuraciones de cliente MCP para Claude Desktop, Cline, etc.

📋 Requisitos Previos

  • Python 3.8+
  • Docker (con el daemon en ejecución)
  • AWS CLI configurado con los permisos apropiados
  • Repositorio AWS ECR (creado si se usa el push a ECR)
  • Clúster AWS ECS (creado si se despliega)

Instalar uv

# 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"

📖 Inicio Rápido

Modo de Comando Directo (Sin Archivo de Configuración)

La forma más rápida de construir imágenes de servidor MCP es usando el modo de comando directo:

# 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

Archivos de Configuración

Usa archivos de configuración basados en yaml con archivos de configuración para despliegues complejos:

# Install from a Git repository
uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --config your-config.yaml

Configuración de Desarrollo Local (MacOS o 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

⚙️ Configuración

La herramienta soporta dos modos:

  1. Modo de Comando Directo: No se necesita archivo de configuración - especifica el comando directamente con el separador --
  2. Modo de Archivo de Configuración: Usa archivos de configuración YAML para construcciones y despliegues complejos

Modo de Comando Directo

Usa el separador -- para especificar comandos directamente:

# 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

Características:

  • No se requiere archivo de configuración
  • Extracción automática del nombre del paquete para el nombrado de imágenes Docker
  • Soporte multi-arquitectura con el parámetro --arch (linux/amd64, linux/arm64, etc.)
  • Modo solo-construcción (el despliegue requiere archivos de configuración)
  • Soporte simple de la bandera --push-to-ecr

Modo de Archivo de Configuración

Para escenarios complejos, usa archivos de configuración YAML con las secciones build y deploy:

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"

🔧 Uso Avanzado

Dockerfile Personalizado

build:
  github_url: "https://github.com/my-org/custom-mcp-server"
  dockerfile_path: "./custom/Dockerfile"
  push_to_ecr: true
deploy:
  enabled: true
  # ... deployment configuration

Variables de Entorno en el Contenedor

Establece variables de entorno personalizadas que estarán disponibles para el servidor MCP en tiempo de ejecución:

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

Variables de Entorno del Sistema

Establece variables de entorno para sobrescribir la configuración predeterminada de AWS:

export AWS_REGION=us-west-2
export ECS_CLUSTER_NAME=my-production-cluster

🏗️ Arquitectura

Flujo del Proceso de Construcción

La herramienta soporta dos modos de construcción:

Modo de Comando Directo

  1. Análisis de Comando: Analiza el comando y los argumentos desde la CLI usando el separador -- (ej., -- npx -y @modelcontextprotocol/server-everything)
  2. Extracción del Nombre del Paquete: Extrae automáticamente los nombres de paquete para el nombrado de imágenes Docker (ej., @modelcontextprotocol/server-everything → mcp-server-everything)
  3. Detección de Lenguaje: Detecta el tiempo de ejecución (Node.js/Python) desde el comando
  4. Generación de Dockerfile: Crea contenedores optimizados con paquetes preinstalados
  5. Construcción de Imagen: Construye el contenedor listo para ejecutar el comando especificado

Modo de Archivo de Configuración (GitHub/Entrypoint)

  1. Análisis de Repositorio: Descarga repositorios de GitHub y detecta la configuración del servidor MCP desde archivos README (modo GitHub)
  2. Detección de Lenguaje: Detecta automáticamente Python o Node.js/TypeScript según los archivos del proyecto (package.json, pyproject.toml, etc.)
  3. Detección de Comando: Analiza bloques JSON en archivos README para extraer comandos de inicio del servidor MCP desde los formatos de configuración de Claude Desktop (mcpServers) y VS Code (mcp.servers)
  4. Generación de Dockerfile: Usa plantillas Jinja2 específicas del lenguaje (Dockerfile-python.j2, Dockerfile-nodejs.j2) para crear construcciones optimizadas con integración de la CLI mcp-proxy
  5. Construcción de Imagen: Crea contenedores específicos del lenguaje con gestión adecuada de dependencias y construcciones de múltiples etapas

Arquitectura de Despliegue

GitHub Repo → Docker Build → ECR → ECS Fargate ← ALB ← Internet
     ↓              ↓           ↓         ↓        ↓
MCP Server → mcp-proxy + MCP → Image → Service → HTTP/SSE Endpoints

Soporte y Detección de Lenguaje

La herramienta soporta servidores MCP de Python y Node.js/TypeScript con detección automática de lenguaje:

Proyectos Python

  • Detectados por: archivos pyproject.toml, requirements.txt, setup.py o .py
  • Gestores de paquetes: pip, uv, poetry (detectados automáticamente)
  • Imagen base: python:3.12-slim-bookworm
  • Extracción de comandos desde: scripts de consola en pyproject.toml, puntos de entrada en setup.py

Proyectos Node.js/TypeScript

  • Detectados por: archivos package.json, tsconfig.json o .ts/.js
  • Gestor de paquetes: npm (con imagen base Node.js 24-bullseye)
  • Imagen base: node:24-bullseye
  • Extracción de comandos desde: configuraciones JSON en README

Detección y Sobrescritura de Comandos

La herramienta detecta automáticamente los comandos de inicio del servidor MCP desde:

  1. Archivos README - Bloques de configuración JSON que soportan ambos formatos:
    • Claude Desktop: {"mcpServers": {...}}
    • VS Code: {"mcp": {"servers": {...}}}
  2. Proyectos Python - Scripts de consola pyproject.toml, puntos de entrada setup.py
  3. Proyectos Node.js - Configuraciones en README (los scripts de package.json no se analizan)

Se Requiere Sobrescritura de Comando Cuando:

  • El README solo contiene comandos Docker (no adecuados para contenerización)
  • No se puede detectar un comando de inicio adecuado
  • Quieres especificar parámetros de inicio exactos

Ejemplo:

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

Ejemplos de Configuraciones README Soportadas:

Formato Claude Desktop:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Formato VS Code:

{
  "mcp": {
    "servers": {
      "everything": {
        "command": "python",
        "args": ["-m", "server"]
      }
    }
  }
}

Ejemplo de Error:

Si el README de tu servidor MCP solo muestra comandos Docker:

{
  "mcpServers": {
    "myserver": {
      "command": "docker",
      "args": ["run", "myserver:latest"]
    }
  }
}

Recibirás un error que requiere command_override para especificar el comando de inicio directo.

🐛 Solución de Problemas

Problemas de Construcción Docker

  • Asegúrate de que el daemon de Docker esté en ejecución
  • Verifica que el servidor MCP tenga los archivos de dependencias adecuados (requirements.txt, pyproject.toml, etc.)
  • Verifica que la URL del repositorio de GitHub sea accesible

Problemas de Construcción Multi-Arquitectura

Al usar el parámetro --arch o architecture en archivos de configuración, puedes encontrar:

Error: "No builder available for architecture"

Esto significa que Docker Buildx no está configurado correctamente. Para solucionarlo:

# 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

Arquitecturas soportadas:

  • linux/amd64 - x86-64 estándar (Intel/AMD)
  • linux/arm64 - ARM de 64 bits (Apple Silicon, AWS Graviton)

Para más información, visita: https://docs.docker.com/build/building/multi-platform/

Problemas de Push a ECR

  • Asegúrate de que las credenciales de AWS tengan permisos de ECR
  • Verifica que el repositorio ECR exista y sea accesible
  • Comprueba que Docker esté autenticado con ECR

Problemas de Despliegue con CloudFormation

  • Asegúrate de que las credenciales de AWS tengan permisos suficientes
  • Comprueba que el clúster ECS exista
  • Verifica que la región de AWS sea correcta
  • Revisa los eventos de CloudFormation en la Consola de AWS para ver mensajes de error detallados

Problemas de Conexión del Servidor MCP

  • Revisa los registros del contenedor en la configuración local: docker logs <container-id>
  • Verifica el endpoint de verificación de salud: curl http://<alb-url>/mcp (espera HTTP 400)
  • Prueba la conexión directa: curl http://<alb-url>/mcp
  • Usa el modo de depuración para un registro detallado

🔐 Permisos de AWS Requeridos

Las credenciales de AWS utilizadas deben tener los siguientes permisos:

Permisos de ECR

{
  "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": "*"
    }
  ]
}

Permisos de ECS y CloudFormation

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:*",
        "cloudformation:*",
        "ec2:*",
        "elasticloadbalancing:*",
        "iam:CreateRole",
        "iam:AttachRolePolicy",
        "iam:PassRole",
        "logs:CreateLogGroup",
        "logs:DescribeLogGroups"
      ],
      "Resource": "*"
    }
  ]
}

📝 Configuración del Cliente MCP

Después del despliegue, la herramienta genera la configuración para los clientes MCP:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "sse",
      "url": "http://<ALB address>/sse"
    }
  }
}

Prueba de la Conexión MCP

# Install mcp-proxy client
npm install -g mcp-proxy

# Test connection
mcp-proxy https://your-alb-url.amazonaws.com/mcp

Seguridad

Consulta CONTRIBUTING para más información.

Licencia

Esta biblioteca está licenciada bajo la Licencia MIT-0. Consulta el archivo LICENSE.

🆘 Soporte

  • Consulta la sección de solución de problemas para problemas comunes
  • Revisa los eventos de CloudFormation en la Consola de AWS para problemas de despliegue
  • Usa el modo de depuración para un registro detallado
  • Abre un issue para errores o solicitudes de funciones