# Amazon ECS MCP 서버 시작하기
<a name="ecs-mcp-getting-started"></a>

이 가이드에서는 AI 코드 어시스턴트와 함께 Amazon ECS MCP 서버를 설정하고 사용하는 단계를 안내합니다. 환경을 구성하고, 서버에 연결하며, 자연어 상호 작용을 통해 Amazon ECS 클러스터 관리를 시작하는 방법에 대해 알아봅니다.

**참고**  
Amazon ECS MCP 서버는 Amazon ECS 미리 보기 릴리스에 있으므로 변경될 수 있습니다.

## 사전 조건
<a name="ecs-mcp-prerequisites"></a>

시작하기 전에 다음을 갖추었는지 확인하세요.
+ [Amazon ECS에 액세스할 수 있는 AWS 계정을 생성함](https://aws.amazon.com/resources/create-account/)
+ [자격 증명으로 AWS CLI를 설치 및 구성함](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
+ [Python 3.10 이상을 설치함](https://www.python.org/)
+ [uv를 설치함](https://docs.astral.sh/uv/getting-started/installation/)

## 설정
<a name="ecs-mcp-setup"></a>

### 사전 조건 확인
<a name="ecs-mcp-verify-prerequisites"></a>

Python 버전이 3.10 이상인지 확인합니다.

```
python3 --version
```

uv 설치 확인

```
uv --version
```

AWS CLI 구성 확인

```
aws configure list
```

### IAM 권한 설정
<a name="ecs-mcp-iam-permissions"></a>

AWS 서비스에 대한 읽기 전용 요청을 하고 MCP 서버와 상호 작용하려면 [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 권한이 필요합니다. [AWS 관리형 정책](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html)을 활용하거나 세분화된 제어를 위해서는 단일 사용자 지정 정책을 활용할 수 있습니다.

**옵션 1: 관리형 정책 및 사용자 지정 정책 결합**

1. 모든 AWS 서비스에 대한 읽기 전용 액세스를 위해 AWS 관리형 정책 **ReadOnlyAccess** 연결

1. MCP 권한에 대한 추가 사용자 지정 정책 생성 및 연결(아래 MCP 권한 JSON 참조).

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

**옵션 2: 단일 사용자 지정 정책(가장 세분화된 제어)**

또는 AWS 서비스 권한과 MCP 권한을 모두 포함하는 단일 사용자 지정 JSON 정책을 생성하고 연결할 수 있습니다.

```
{
  "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": "*"
    }
  ]
}
```

### AI 어시스턴트 선택 및 구성
<a name="ecs-mcp-configure-assistant"></a>

MCP 호환 AI 어시스턴트 또는 MCP 호환 도구를 설치합니다. 예를 들어 [Kiro](https://kiro.dev/), [Cline](https://cline.bot/), [Cursor](https://cursor.com/) 또는 [Claude Code](https://www.claude.com/product/claude-code)를 사용할 수 있습니다. 그런 다음 Amazon ECS MCP 서버에 대한 안전하고 인증된 액세스에 필요한 AWS용 MCP 프록시를 통해 Amazon ECS MCP 서버를 사용하도록 AI 코드 어시스턴트를 설정합니다. 프록시는 클라이언트 측 브리지 역할을 하여 로컬 AWS 자격 증명을 사용해 AWS SigV4 인증을 처리합니다. 아래 예제에서는 Kiro CLI를 사용합니다. Kiro에서 MCP를 설정하는 방법에 대해 자세히 알아보려면 이 [링크](https://kiro.dev/docs/cli/mcp/)를 따라 이동하세요.

#### MCP 구성 파일 찾기
<a name="ecs-mcp-kiro-config-file"></a>
+ **macOS/Linux:**

  ```
  ~/.kiro/settings/mcp.json
  ```
+ **(Windows)**

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

구성 파일이 없는 경우 생성합니다.

#### MCP 서버 구성 추가
<a name="ecs-mcp-kiro-add-config"></a>

리전(`{region}`) 자리 표시자를 원하는 리전(예: `us-west-2`)으로 바꿔야 합니다. 전체 리전 목록은 [AWS Fargate의 Linux 컨테이너](AWS_Fargate-Regions.md#linux-regions) 섹션을 참조하세요. 또한 `{profile}` 자리 표시자를 [AWS CLI 프로파일 이름](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html)(예: `default`)으로 바꿔야 합니다.

**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}"
      ]
    }
  }
}
```

**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}"
      ]
    }
  }
}
```

#### 구성 확인
<a name="ecs-mcp-kiro-verify"></a>

Kiro CLI를 다시 시작하고(`kiro-cli`), MCP 서버가 로드되었는지 확인하며(`/mcp`), 사용 가능한 도구를 확인합니다(`/tools`).

#### 설정 확인
<a name="ecs-mcp-verify-setup"></a>

**연결 테스트**

AI 어시스턴트에 연결을 확인하기 위한 간단한 질문을 합니다.

```
List all ECS clusters in my AWS account
```

Amazon ECS 클러스터 목록이 표시됩니다.

#### Amazon ECS MCP 서버를 사용하는 AI 어시스턴트와 대화
<a name="ecs-mcp-first-tasks"></a>

**예제 1: 배포 모니터링**

```
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
```

**예제 2: 컨테이너 상태 조사**

```
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
```

**예제 3: 장애 문제 해결**

```
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?
```

**예제 4: 구성 검사**

```
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
```

## 일반적인 구성 및 모범 사례
<a name="ecs-mcp-common-configs"></a>

### 다중 AWS 프로필
<a name="ecs-mcp-multiple-profiles"></a>

여러 AWS 계정으로 작업하는 경우 별도의 MCP 서버 구성을 생성합니다.

**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"
      ]
    }
  }
}
```

### 보안 모범 사례
<a name="ecs-mcp-security-best-practices"></a>

허용된 입력 메커니즘을 통해 보안 암호 또는 민감한 정보를 전달하지 마세요.
+ 구성 파일에 보안 암호 또는 자격 증명 포함 안 함
+ 프롬프트에서 민감한 정보를 모델에 직접 전달 안 함
+ 태스크 정의 또는 서비스 구성에 보안 암호 포함 안 함
+ 애플리케이션 로그에 민감한 정보 로깅 방지
+ 또는 Parameter Store를 사용하여 민감한 정보 저장

## 도구 구성
<a name="ecs-mcp-next-steps"></a>

전체 도구 및 구성 목록은 [Amazon ECS MCP 서버 도구 구성](ecs-mcp-tool-configurations.md) 섹션을 참조하세요.