# 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:
+ [Created an Amazon account with access to Amazon ECS](https://aws.amazon.com/resources/create-account/)
+ [Installed and configured the Amazon 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 Amazon 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 Amazon services and interact with the MCP server. You can either leverage [Amazon 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 Amazon managed policy **ReadOnlyAccess** for read-only access to all Amazon 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 Amazon 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 Amazon, which is required for secure, authenticated access to the Amazon ECS MCP Server. The proxy acts as a client-side bridge, handling Amazon SigV4 authentication using your local Amazon 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 Amazon Fargate](AWS_Fargate-Regions.md#linux-regions) for a complete list of regions. Also be sure to replace the `{profile}` placeholder with your [Amazon 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 Amazon profiles
If you work with multiple Amazon 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).