mcp-server-aws-ecs by waneal - MCP Server

[!NOTE]
If you can use Claude Code in Claude Desktop, it may be useful to use aws-cli via bash tool in Claude Code rather than this mcp server.

AWS ECS MCP Server

A Model Context Protocol (MCP) server for interacting with Amazon ECS (Elastic Container Service). This MCP server provides a set of tools that allow LLMs to list, describe, and manage ECS clusters, services, and tasks.

AWS ECS MCP Server

Overview

This MCP server provides a bridge between Large Language Models (LLMs) and AWS ECS resources. It enables LLMs to query and interact with ECS clusters, services, tasks, and related resources using MCP tools. The server wraps the AWS boto3 ECS client API and exposes it through the MCP protocol.

Prerequisites

Python 3.11 or higher
AWS account with ECS access
AWS credentials configured locally
Claude for Desktop (for integration with Claude)

Installation

Step 1: Clone the repository

git clone https://github.com/waneal/mcp-server-aws-ecs.git
cd mcp-server-aws-ecs

Step 2: Install uv (Python package manager)

We recommend using uv, a fast Python package installer and resolver.

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

Usage

Running the server

You can run the server directly with uv, choosing the type of server you need:

# For full server (read + write operations)
export AWS_PROFILE=your-profile-name
export AWS_REGION=ap-northeast-1  # Optional, defaults to ap-northeast-1
uv run server.py

# For read-only operations
uv run read_server.py

# For write operations only
uv run write_server.py

Using with Claude for Desktop

To use this server with Claude for Desktop:

Manually configure Claude Desktop by editing your configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json

Create or edit the file to include the following (choose the server type you need):

{
  "mcpServers": {
    "aws-ecs-full": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-server-aws-ecs",
        "run",
        "server.py"
      ],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "ap-northeast-1"
      }
    },
    "aws-ecs-read": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-server-aws-ecs",
        "run",
        "read_server.py"
      ],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "ap-northeast-1"
      }
    }
  }
}

For Windows, use a path format like:

{
  "mcpServers": {
    "aws-ecs-full": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\mcp-server-aws-ecs",
        "run",
        "server.py"
      ],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "ap-northeast-1"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration file.
Verify the server is connected:
- Look for the hammer icon 🔨 in the bottom right corner of the input box
- Click on it to see the available AWS ECS tools
- If tools are not showing up, check the troubleshooting section below
Start a new conversation in Claude Desktop, and the ECS tools will be available to Claude.

Troubleshooting

If your MCP server doesn't connect properly:

Restart Claude Desktop completely
Check your claude_desktop_config.json file syntax
Make sure the file paths are valid and absolute (not relative)
Check Claude's logs:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%\Claude\logs\mcp*.log
Try running the server manually to check for errors:
```
cd /path/to/mcp-server-aws-ecs
uv run server.py
```

Available Tools

This server provides the following ECS tools:

Cluster operations: list_clusters, describe_clusters, create_cluster, delete_cluster
Service operations: list_services, describe_services, list_services_with_details, create_service, update_service, delete_service
Task operations: list_tasks, describe_tasks, get_task_protection, update_task_protection, run_task, stop_task
Container instance operations: list_container_instances, describe_container_instances
Task definition operations: list_task_definitions, list_task_definition_families, register_task_definition, deregister_task_definition
Capacity provider operations: list_capacity_providers, describe_capacity_providers, get_cluster_capacity_providers, create_capacity_provider, delete_capacity_provider
Task set operations: describe_task_sets, create_task_set, update_task_set, delete_task_set
Deployment operations: list_service_deployments, describe_service_deployments, describe_service_revisions
Miscellaneous: list_account_settings, list_attributes, list_tags_for_resource, list_services_by_namespace, discover_poll_endpoint, delete_account_setting, delete_attributes

Server Types

This package provides three different server types to match your needs:

Full Server (server.py):
- Includes both read and write operations
- Provides complete access to all AWS ECS APIs
- Use when you need full control over your ECS resources
Read-Only Server (read_server.py):
- Includes only read operations (list_, describe_, get_)
- Safer option as it can't modify your infrastructure
- Ideal for monitoring and exploring your ECS environment
Write Server (write_server.py):
- Includes only write operations (create_, update_, delete_)
- Focused on infrastructure changes
- Useful for deployments and infrastructure management

You can choose the appropriate server based on your needs and security requirements.

Configuration

The server uses these environment variables that can be configured in the env section of the claude_desktop_config.json file:

AWS_PROFILE: AWS profile name from your AWS credentials file
AWS_REGION: AWS region (defaults to ap-northeast-1)
AWS_ACCESS_KEY_ID: AWS access key (alternative to profile)
AWS_SECRET_ACCESS_KEY: AWS secret key (alternative to profile)
AWS_SESSION_TOKEN: AWS session token (if using temporary credentials)

License

This project is licensed under the MIT License - see the LICENSE file for details.