# AWS ECS MCP Server

An MCP (Model Context Protocol) server that exposes AWS ECS operations as tools, allowing AI assistants to manage ECS clusters, services, tasks, and view container logs.

## Features

### Read Operations
- **list_clusters** / **describe_cluster** — View clusters and their capacity
- **list_services** / **describe_service** — View services, deployments, and load balancer config
- **list_tasks** / **describe_task** — View tasks, container status, and networking
- **list_task_definitions** / **describe_task_definition** — View task definitions with full container config
- **get_service_events** — View recent deployment events and errors
- **get_container_logs** — Fetch CloudWatch logs for a container (auto-discovers log group from task definition)

### Write Operations
- **update_service_desired_count** — Scale a service up or down
- **force_new_deployment** — Trigger a rolling deployment
- **run_task** — Run one-off tasks (migrations, batch jobs)
- **stop_task** — Stop a running task
- **register_task_definition** — Register a new task definition revision

## Installation

```bash
pip install -e .
```

## Configuration

### AWS Credentials

Uses the standard boto3 credential chain:
- Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
- AWS config files (`~/.aws/credentials`, `~/.aws/config`)
- IAM instance roles / ECS task roles

Set your default region:
```bash
export AWS_DEFAULT_REGION=us-east-1
```

All tools accept an optional `region` parameter to override the default.

### MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "aws-ecs": {
      "command": "aws-ecs-mcp"
    }
  }
}
```

Or run directly:
```bash
aws-ecs-mcp
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v
```

## Available Tools

| Tool | Type | Description |
|------|------|-------------|
| `list_clusters` | Read | List all ECS clusters |
| `describe_cluster` | Read | Get cluster details |
| `list_services` | Read | List services in a cluster |
| `describe_service` | Read | Get service details with deployments |
| `get_service_events` | Read | Recent service events |
| `list_tasks` | Read | List tasks (filterable by service/status) |
| `describe_task` | Read | Full task details with containers |
| `list_task_definitions` | Read | List task definition families |
| `describe_task_definition` | Read | Full task definition spec |
| `get_container_logs` | Read | CloudWatch logs for a container |
| `update_service_desired_count` | Write | Scale a service |
| `force_new_deployment` | Write | Force rolling deployment |
| `run_task` | Write | Run a one-off task |
| `stop_task` | Write | Stop a running task |
| `register_task_definition` | Write | Register new task def revision |