# Amazon ECS MCP server
Amazon ECS MCP server

The Amazon ECS MCP server is a fully managed service enabling AI-powered experiences for development and operations. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) provides a standardized interface that enriches AI agents and applications with real-time, contextual knowledge of your Amazon ECS workloads, enabling more accurate, context-aware responses and AI-powered workflows to inspect, troubleshoot, and optimize your Amazon ECS workloads.

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

## Overview


The Amazon ECS MCP server can be easily integrated with any MCP compatible AI coding assistants, like [Kiro](https://kiro.dev/), or third-party tools like [Claude Code](https://code.claude.com/docs/en/mcp), [Cursor](https://cursor.com/), and [Cline](https://cline.bot/), to enhance your development workflow.

During deployment, it provides real-time visibility into service deployments and task health status. For development and operations, the server simplifies Amazon ECS management by providing high-level workflows for monitoring container health, analyzing service events, and investigating deployment issues. For debugging and troubleshooting, the server accelerates issue resolution through comprehensive diagnostic tools that analyze task failures, container logs, and network configurations. These capabilities are accessible through natural language interactions, enabling you to perform complex container operations more intuitively and efficiently.

The Amazon ECS MCP server provides several tools that you can use to:
+ **Monitor deployments and services**

  Check deployment status, track service events, and monitor container health in real-time.
+ **Troubleshoot container issues**

  Analyze task failures, investigate image pull errors, and examine container logs with customizable time windows.
+ **Inspect network configurations**

  Review VPC, subnet, and security group configurations for your Amazon ECS services.
+ **Resolve resource dependencies**

  Identify blockers preventing task definition deletion and understand resource relationships.

The fully managed Amazon ECS MCP server is hosted in the AWS cloud, eliminating the need for local installation and maintenance. It provides enterprise-grade capabilities like automatic updates and patching, centralized security through IAM integration, comprehensive audit logging via CloudTrail, and the proven scalability, reliability, and support of AWS.

## Getting started


To get started, see [Getting Started with the Amazon ECS MCP Server](ecs-mcp-getting-started.md).

# Getting Started with the Amazon ECS MCP Server
Getting started

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:
+ [Created an AWS account with access to Amazon ECS](https://aws.amazon.com/resources/create-account/)
+ [Installed and configured the AWS CLI with credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
+ [Installed Python 3.10\$1](https://www.python.org/)
+ [Installed uv](https://docs.astral.sh/uv/getting-started/installation/)

## 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) permissions to make read-only requests to AWS services and interact with the MCP server. You can either leverage [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html), 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

1. 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](https://kiro.dev/), [Cline](https://cline.bot/), [Cursor](https://cursor.com/), or [Claude Code](https://www.claude.com/product/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](https://kiro.dev/docs/cli/mcp/) 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](AWS_Fargate-Regions.md#linux-regions) for a complete list of regions. Also be sure to replace the `{profile}` placeholder with your [AWS CLI profile name](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html), 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](ecs-mcp-tool-configurations.md).

# Amazon ECS MCP Server Tool Configurations
Tool configurations

This guide shows all the configurations available for the fully managed Amazon ECS MCP Server.

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

## Environment variables


**AWS\$1PROFILE** (optional)  
AWS credentials profile name to use; can be overridden by the `--profile` command-line argument.  
Example: `export AWS_PROFILE=dev`

**AWS\$1REGION** (optional)  
AWS region for SigV4 signing; defaults to `us-west-2` if not set.  
Example: `export AWS_REGION=us-west-2`

## Arguments


**SigV4 MCP endpoint URL** (required)  
The MCP endpoint URL to connect to.  
Example: `https://ecs-mcp.us-west-2.api.aws/mcp`

**--service** (optional)  
AWS service name for SigV4 signing; auto-detected from the endpoint hostname if not provided.  
Example: `--service ecs-mcp`

**--profile** (optional)  
AWS credentials profile to use. Defaults to the `AWS_PROFILE` environment variable if not specified.  
Example: `--profile dev`

**--region**  
AWS region to use. Uses `AWS_REGION` environment variable if not set, defaults to `us-east-1`.  
Example: `--region us-west-2`

**--read-only** (optional)  
Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with `readOnlyHint=true`). By default, all tools are enabled.  
Example: `--read-only`

For more configuration options, see [Configuration parameters](https://github.com/aws/mcp-proxy-for-aws?tab=readme-ov-file#configuration-parameters).

## Tools


The Amazon ECS MCP server exposes the following [MCP tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).

### Read only tools


**get\$1deployment\$1status**  
The tool checks your Amazon ECS deployment status for a particular Amazon ECS cluster and service.  
+ Required IAM actions:
  + `ecs:DescribeServices`
  + `elasticloadbalancing:DescribeTargetGroups`
  + `elasticloadbalancing:DescribeLoadBalancers`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name
  + `service_name` (string): Amazon ECS service name
+ Response: The tool returns deployment status and details associated with the deployment.

**fetch\$1service\$1events**  
This tool retrieves Amazon ECS service events for diagnostics with customizable time windows.  
+ Required IAM actions:
  + `ecs:DescribeServices`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name
  + `service_name` (string): Amazon ECS service name
+ Optional parameters:
  + `time_window` (integer): You can mention a time window in seconds (default is 1 hour or 3600 seconds)
  + `start_time` (string): Custom start time in ISO format
  + `end_time` (string): Custom end time in ISO format
+ Response: The tool returns list of events for the service with summary.

**fetch\$1task\$1failures**  
This tool helps you retrieve and analyze Amazon ECS task failures with summaries. Using this tool, you can identify any patterns in task failures.  
+ Required IAM actions:
  + `ecs:ListTasks`
  + `ecs:DescribeTasks`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name where your task resides
+ Optional parameters:
  + `service_name` (string): You can filter by specific service
  + `time_window` (integer): You can mention a time window in seconds (default is 1 hour or 3600 seconds)
  + `start_time` (string): Custom start time in ISO format
  + `end_time` (string): Custom end time in ISO format
+ Response: The tool returns TaskFailureResult with failed tasks and summary

**fetch\$1task\$1logs**  
This tool retrieves CloudWatch logs for Amazon ECS tasks with flexible time range options. You use this tool to troubleshoot runtime issues.  
+ Required IAM actions:
  + `ecs:DescribeServices`
  + `ecs:DescribeTaskDefinition`
  + `logs:FilterLogEvents`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name
  + `service_name` (string): Amazon ECS service name
+ Optional parameters:
  + `time_window` (integer): You can mention a time window in seconds (default is 1 hour or 3600 seconds)
  + `start_time` (string): Custom start time in ISO format
  + `end_time` (string): Custom end time in ISO format
  + `log_group_name` (string): Specify CloudWatch log group
+ Response: The tool returns TaskLogsResult with log entries

**get\$1task\$1definition\$1deletion\$1blockers**  
This tool identifies dependencies that can prevent task definition deletion. The tool is appropriate when you are running cleanup operations and understand what is preventing Amazon ECS resource deletion.  
+ Required IAM actions:
  + `ecs:ListClusters`
  + `ecs:ListServices`
  + `ecs:DescribeServices`
  + `ecs:ListTasks`
  + `ecs:DescribeTasks`
+ Required parameters:
  + `task_definition_arn` (string): Task definition Amazon Resource Name (ARN) to analyze
+ Response: The tool returns the blockers and deletion status

**detect\$1image\$1pull\$1failures**  
This tool helps you to detect and categorize container image pull failures.  
+ Required IAM actions:
  + `ecs:ListTasks`
  + `ecs:DescribeTasks`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name
+ Optional parameters:
  + `service_name` (string): You can filter by specific service
  + `time_window` (integer): You can mention a time window in seconds (default is 1 hour or 3600 seconds)
  + `start_time` (string): Custom start time in ISO format
  + `end_time` (string): Custom end time in ISO format
+ Response: The tool returns the failures and summary

**fetch\$1network\$1configuration**  
This tool retrieves Amazon ECS service network configuration details. You can use this tool to understand the Amazon VPC, subnet, security group configuration of your Amazon ECS setup.  
+ Required IAM actions:
  + `ecs:DescribeServices`
  + `ec2:DescribeSecurityGroups`
  + `ec2:DescribeSubnets`
+ Required parameters:
  + `cluster_name` (string): Amazon ECS cluster name
  + `service_name` (string): Amazon ECS service name
+ Response: The tool returns a list of NetworkConfigurationResult with network details