AWS CLI MCP server

The AWS Model Context Protocol (MCP) Server enables AI assistants to execute AWS CLI commands through a secure interface. This lightweight service bridges AI tools like Claude Desktop with AWS resources, allowing assistants to retrieve AWS documentation and run AWS commands with proper formatting and security controls.

Installation Options

Using Docker (Recommended)

# Pull the official image
docker pull ghcr.io/alexei-led/aws-mcp-server:latest

# Or run with docker-compose
docker compose -f deploy/docker/docker-compose.yml up -d

The Docker image supports both AMD64/x86_64 and ARM64 architectures automatically.

Using Python (Alternative)

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Set up virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Run the server
python -m aws_mcp_server

Configuration

Configure the server using these environment variables:

Integrating with Claude Desktop

1. Locate the Claude Desktop configuration file:

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

2. Edit the configuration file:

   {
     "mcpServers": {
       "aws-mcp-server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
           "ghcr.io/alexei-led/aws-mcp-server:latest"
         ]
       }
     }
   }
   

3. Restart Claude Desktop to apply the changes

Security Best Practices

Use Docker Container Deployment

Running in a Docker container is strongly recommended as it provides:

• Isolation from your host system's filesystem
• Containment of potentially destructive commands
• A controlled, consistent environment

Apply IAM Least Privilege

• Use IAM credentials with minimal necessary permissions
• Never use root AWS credentials
• Regularly review and audit permissions
• IAM permissions are the primary mechanism for limiting potential impact

Additional Security Measures

• The server validates all AWS CLI commands through multiple security layers
• Dangerous commands like IAM user creation are blocked by default
• Security modes: strict (default) or permissive
• Custom security rules can be defined via YAML configuration file

Example Interactions

Getting AWS CLI Documentation

User: What are the available options for the AWS S3 cp command?

Claude: Let me get that information for you.

The AWS S3 cp command has the following options:

NAME
    cp - Copies a local file or S3 object to another location locally or in S3.

SYNOPSIS
    cp <LocalPath> <S3Uri> or <S3Uri> <LocalPath> or <S3Uri> <S3Uri> [--acl <value>] [--cache-control <value>] ...

Executing AWS CLI Commands

User: List my S3 buckets

Claude: I'll list your S3 buckets for you.

2023-10-15 14:30:45 my-bucket-1
2023-11-20 09:15:32 my-bucket-2
2024-01-05 11:22:18 my-backup-bucket

Using Command Pipes

User: List my S3 buckets that have "backup" in their name and show them in alphabetical order

Claude: Let me find that for you.

2024-01-05 11:22:18 my-backup-bucket
2024-03-01 09:44:12 weekly-backup-bucket
2024-03-15 13:10:57 database-backup-bucket

Troubleshooting

• Authentication Issues: Ensure AWS credentials are properly configured
• Connection Errors: Verify the server is running and AI assistant connection settings are correct
• Permission Errors: Check that your AWS credentials have the necessary permissions
• Timeout Errors: For long-running commands, increase the AWS_MCP_TIMEOUT environment variable

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.