Getting Started with the Amazon ECS MCP Server - Amazon Elastic Container Service
PrerequisitesSetupCommon configurations and best practicesTool configurations

Getting Started with the Amazon ECS MCP Server

This guide walks you through the steps to set up and use the Amazon ECS MCP Server with your AI code assistants. You'll learn how to configure your environment, connect to the server, and start managing your Amazon ECS clusters through natural language interactions.

Note

The Amazon ECS MCP server is in preview release and is subject to change.

Prerequisites

Before you begin, ensure you have:

Setup

Verify prerequisites

Check that your Python version is 3.10 or higher

python3 --version

Check uv installation

uv --version

Verify AWS CLI configuration

aws configure list

Set up IAM permissions

You will need IAM permissions to make read-only requests to AWS services and interact with the MCP server. You can either leverage AWS managed policies, or a single custom policy for more granular control.

Option 1: Combined managed and custom policy

  1. Attach the AWS managed policy ReadOnlyAccess for read-only access to all AWS services

  2. Create and attach an additional custom policy for MCP permissions (see MCP permissions JSON below)

{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "MCPServerAccess",
      "Effect": "Allow",
      "Action": [
        "ecs-mcp:InvokeReadOnlyTools",
        "ecs-mcp:UseMcp"
      ],
      "Resource": "*"
    }
  ]
}

Option 2: Single custom policy (most granular control)

Alternatively, you can create and attach a single custom JSON policy that includes both AWS service permissions and MCP permissions:

{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "MCPServerAccess",
      "Effect": "Allow",
      "Action": [
        "ecs-mcp:InvokeReadOnlyTools",
        "ecs-mcp:UseMcp"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ECSReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "ecs:ListAccountSettings",
        "ecs:ListClusters",
        "ecs:ListContainerInstances",
        "ecs:ListTaskDefinitions",
        "ecs:ListServices",
        "ecs:ListServiceDeployments",
        "ecs:ListTasks",
        "ecs:DescribeClusters",
        "ecs:DescribeCapacityProviders",
        "ecs:DescribeContainerInstances",
        "ecs:DescribeTaskDefinition",
        "ecs:DescribeServices",
        "ecs:DescribeServiceDeployments",
        "ecs:DescribeServiceRevisions",
        "ecs:DescribeTaskSets",
        "ecs:DescribeTasks"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:GetLogEvents",
        "logs:FilterLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ELBReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "elasticloadbalancing:DescribeLoadBalancers",
        "elasticloadbalancing:DescribeTargetGroups",
        "elasticloadbalancing:DescribeListeners"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EC2ReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeRouteTables",
        "ec2:DescribeNetworkInterfaces"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ECRReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "ecr:DescribeRepositories",
        "ecr:DescribeImages"
      ],
      "Resource": "*"
    }
  ]
}

Choose and configure an AI assistant

Install MCP-compatible AI assistants or any MCP-compatible tool. For instance, you can use Kiro, Cline, Cursor, or Claude Code. Then set up your AI code assistant to use Amazon ECS MCP server through MCP Proxy for AWS, which is required for secure, authenticated access to the Amazon ECS MCP Server. The proxy acts as a client-side bridge, handling AWS SigV4 authentication using your local AWS credentials. The below example uses Kiro CLI. Follow this link to learn more about setting up MCP in Kiro.

Locate MCP configuration file

  • macOS/Linux:

    ~/.kiro/settings/mcp.json

  • Windows:

    %USERPROFILE%\.kiro\settings\mcp.json

Create the configuration file if it doesn't exist.

Add MCP server configuration

Be sure to replace the region ({region}) placeholder with your desired region (e.g., us-west-2). Refer to the Linux containers on AWS Fargate for a complete list of regions. Also be sure to replace the {profile} placeholder with your AWS CLI profile name, e.g. default.

For Mac/Linux:

{
  "mcpServers": {
    "ecs-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://ecs-mcp.{region}.api.aws/mcp",
        "--service",
        "ecs-mcp",
        "--profile",
        "{profile}",
        "--region",
        "{region}"
      ]
    }
  }
}

For Windows:

{
  "mcpServers": {
    "ecs-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://ecs-mcp.{region}.api.aws/mcp",
        "--service",
        "ecs-mcp",
        "--profile",
        "{profile}",
        "--region",
        "{region}"
      ]
    }
  }
}

Verify configuration

Restart Kiro CLI, kiro-cli, verify that the MCP server is loaded, /mcp, and check available tools /tools.

Verify your setup

Test connection

Ask your AI assistant a simple question to verify the connection:

List all ECS clusters in my AWS account

You should see a list of your Amazon ECS clusters.

Converse with your AI assistant that uses the Amazon ECS MCP server

Example 1: Monitor deployments

Check deployment status for my web-service in production-cluster
Show me the ALB URL for my deployed service
Get service events for the last hour

Example 2: Investigate container health

Show me all tasks that failed in the last 2 hours
Why are my containers failing health checks?
Display container logs for my api-service

Example 3: Troubleshoot failures

Analyze task failures in my production cluster
Check for image pull errors in the last 30 minutes
Why is my task definition stuck in DELETE_IN_PROGRESS state?

Example 4: Inspect configurations

Show me the network configuration for my web-service
What security groups are attached to my service?
List all VPC and subnet details for my ECS service

Common configurations and best practices

Multiple AWS profiles

If you work with multiple AWS accounts, create separate MCP server configurations.

For Mac/Linux:

{
  "mcpServers": {
    "ecs-mcp-prod": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://ecs-mcp.{region}.api.aws/mcp",
        "--service",
        "ecs-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2"
      ]
    },
    "ecs-mcp-dev": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://ecs-mcp.{region}.api.aws/mcp",
        "--service",
        "ecs-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}

Security best practices

Do not pass secrets or sensitive information via allowed input mechanisms:

  • Do not include secrets or credentials in any configuration files

  • Do not pass sensitive information directly in prompts to the model

  • Do not include secrets in task definitions or service configurations

  • Avoid logging sensitive information in application logs

  • Use or Parameter Store to store sensitive information

Tool configurations

For a complete list of tools and configurations, see Amazon ECS MCP Server Tool Configurations.