AWS ECS MCP Server

A Model Context Protocol (MCP) server for monitoring and analyzing AWS ECS (Elastic Container Service) metrics and services.

Features

• ECS Service Monitoring: Check service status, health, and deployment information
• CloudWatch Metrics: Get CPU, memory, and custom metrics for ECS services
• Load Balancer Integration: Monitor target group health and response times
• IAM Role Support: Works seamlessly with EC2 instance roles and ECS task roles
• Intelligent Name Matching: Uses AI to find the correct cluster and service names

Installation

Install directly from GitHub using pipx:

# Install
pipx install git+https://github.com/neoai-agent/ecs-mcp.git

# Or run without installation
pipx run git+https://github.com/neoai-agent/ecs-mcp.git

Quick Start

On EC2 with IAM Role (Recommended)

ecs-mcp --openai-api-key "YOUR_OPENAI_API_KEY" --region "YOUR_AWS_REGION"

With Explicit AWS Credentials

ecs-mcp --openai-api-key "YOUR_OPENAI_API_KEY" --access-key "YOUR_AWS_ACCESS_KEY" --secret-access-key "YOUR_AWS_SECRET_KEY" --region "YOUR_AWS_REGION"

Available Tools

The server provides the following tools for AWS ECS analysis:

1. check_ecs_service_status: Get comprehensive service status including:

   • Running vs desired task count
   • Deployment status
   • Container images
   • Target group health
   • Unhealthy tasks

2. get_service_metrics: Get CloudWatch metrics for ECS services:

   • CPU utilization
   • Memory utilization
   • Custom metrics

3. get_ecs_target_group_response_time: Monitor load balancer response times

4. get_ecs_target_group_request_metrics: Get request count and error metrics

5. get_ecs_services: List all services in a cluster

IAM Permissions

For EC2 instance role or ECS task role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:ListClusters",
                "ecs:DescribeClusters",
                "ecs:ListServices",
                "ecs:DescribeServices",
                "ecs:ListTasks",
                "ecs:DescribeTasks",
                "ecs:DescribeTaskDefinition",
                "elasticloadbalancing:DescribeTargetHealth",
                "cloudwatch:GetMetricData",
                "cloudwatch:GetMetricStatistics"
            ],
            "Resource": "*"
        }
    ]
}

Development

For development setup:

git clone https://github.com/neoai-agent/ecs-mcp.git
cd ecs-mcp
python -m venv ecs-venv
source ecs-venv/bin/activate  # On Windows: ecs-venv\Scripts\activate
pip install -e ".[dev]"

License

MIT License - See LICENSE file for details