aws-ecs-mcp

AWS ECS MCP Server

An MCP (Model Context Protocol) server that exposes AWS ECS operations as tools, allowing AI assistants to manage ECS clusters, services, tasks, and view container logs.

Features

Read Operations

• list_clusters / describe_cluster — View clusters and their capacity
• list_services / describe_service — View services, deployments, and load balancer config
• list_tasks / describe_task — View tasks, container status, and networking
• list_task_definitions / describe_task_definition — View task definitions with full container config
• get_service_events — View recent deployment events and errors
• get_container_logs — Fetch CloudWatch logs for a container (auto-discovers log group from task definition)

Write Operations

• update_service_desired_count — Scale a service up or down
• force_new_deployment — Trigger a rolling deployment
• run_task — Run one-off tasks (migrations, batch jobs)
• stop_task — Stop a running task
• register_task_definition — Register a new task definition revision

Installation

pip install -e .

Configuration

AWS Credentials

Uses the standard boto3 credential chain:

• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• AWS config files (~/.aws/credentials, ~/.aws/config)
• IAM instance roles / ECS task roles

Set your default region: ``bash export AWS_DEFAULT_REGION=us-east-1 ``

All tools accept an optional region parameter to override the default.

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "aws-ecs": {
      "command": "aws-ecs-mcp"
    }
  }
}

Or run directly: ``bash aws-ecs-mcp ``

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Available Tools

| Tool | Type | Description | |------|------|-------------| | list_clusters | Read | List all ECS clusters | | describe_cluster | Read | Get cluster details | | list_services | Read | List services in a cluster | | describe_service | Read | Get service details with deployments | | get_service_events | Read | Recent service events | | list_tasks | Read | List tasks (filterable by service/status) | | describe_task | Read | Full task details with containers | | list_task_definitions | Read | List task definition families | | describe_task_definition | Read | Full task definition spec | | get_container_logs | Read | CloudWatch logs for a container | | update_service_desired_count | Write | Scale a service | | force_new_deployment | Write | Force rolling deployment | | run_task | Write | Run a one-off task | | stop_task | Write | Stop a running task | | register_task_definition | Write | Register new task def revision |