AWS MCP Server

A Model Context Protocol (MCP) server that provides Claude Desktop with tools to interact with AWS services using your machine's configured AWS profiles.

Features

• 208 AWS tools across 57 services: EC2, S3, IAM, Lambda, CloudWatch, ECS, RDS, DynamoDB, SQS, SNS, SES, ECR, ElastiCache, API Gateway, CloudFront, Route53, Cost Explorer, Cognito, MemoryDB, DocumentDB, OpenSearch, EKS, Athena, Glue, MWAA, Firehose, Secrets Manager, SSM, Lake Formation, CloudTrail, CloudFormation, KMS, ACM, Kinesis, EMR, SageMaker, VPC, Organizations, Resource Groups, EventBridge, ELB v2, Auto Scaling, Step Functions, WAF v2, GuardDuty, Security Hub, CodePipeline, CodeBuild, CodeDeploy, Redshift, EFS, AWS Backup, and more
• Multi-profile support — use any AWS profile from ~/.aws/config
• Readonly by default — starts in safe mode; use --write to allow mutating operations
• Sensitive data gate — Secrets Manager and decrypted SSM reads require extra authentication even in write-enabled mode
• Structured JSONL logging — every operation is logged to logs/aws_mcp.jsonl
• OpenTelemetry tracing (opt-in) — distributed traces are exported only when OTEL_EXPORTER_OTLP_ENDPOINT is set
• Pre-push security scans — semgrep, gitleaks, trivy, bandit, and pip-audit can block unsafe pushes
• Cross-platform — works on Ubuntu/Linux, macOS, and Windows

Requirements

• Python 3.12+
• AWS CLI configured with profiles (~/.aws/config and ~/.aws/credentials)

Quick Start

1. Setup

cd aws-mcp
chmod +x setup.sh
./setup.sh

Or manually:

python3 -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate         # Windows
pip install -e ".[dev]"

2. Test the server

# Verify it starts (will wait for MCP input on stdin, Ctrl+C to stop)
.venv/bin/python main.py

3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

Add the server to the mcpServers section:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "/absolute/path/to/aws-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/aws-mcp/main.py"
      ]
    }
  }
}

See claude_desktop_config.example.json for a full example with multiple configurations.

Windows configuration

{
  "mcpServers": {
    "aws-mcp": {
      "command": "C:\\path\\to\\aws-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\aws-mcp\\main.py"
      ]
    }
  }
}

4. Restart Claude Desktop

After saving the configuration, restart Claude Desktop. The AWS tools will appear in the tools menu.

CLI Options

Sensitive Data Access

Some operations can return secret or decrypted data directly to the MCP client. These operations now require an extra approval token even when the server is running with --write.

Protected flows:

1. aws_secretsmanager_get_secret_value
2. aws_ssm_get_parameter with with_decryption=true
3. aws_ssm_get_parameters_by_path with with_decryption=true
4. Equivalent sensitive calls made through aws_execute

Set an out-of-band token in the server environment:

export AWS_MCP_SENSITIVE_ACCESS_TOKEN="replace-with-a-long-random-token"

For protected operations, pass all three fields below:

{
  "sensitive_access_token": "replace-with-a-long-random-token",
  "sensitive_access_reason": "incident response for production database access",
  "sensitive_access_acknowledged": true
}

Notes:

1. SSM decryption now defaults to false.
2. KMS metadata tools remain read-only. If a future KMS tool can return plaintext, it must use the same gate.

Available Tools (208 total)

Profile Management

EC2

S3

IAM

Lambda

CloudWatch Logs

CloudWatch Metrics & Alarms

ECS

RDS

DynamoDB

SQS

SNS

SES

ECR

ElastiCache (Redis / Memcached)

ELB v2 (ALB / NLB)

Auto Scaling

API Gateway

CloudFront

Route53

VPC

Cost Explorer

KMS

ACM (Certificate Manager)

Secrets Manager

SSM (Systems Manager)

Cognito

EKS

Kinesis

Firehose

Step Functions

EventBridge

WAF v2

GuardDuty

Security Hub

CodePipeline

CodeBuild

CodeDeploy

Athena

Glue

MWAA (Managed Airflow)

Lake Formation

CloudTrail

CloudFormation

Redshift

EFS (Elastic File System)

AWS Backup

EMR

SageMaker

OpenSearch

DocumentDB

MemoryDB

Organizations

Resource Groups & Tag Manager

General

Readonly Mode

The server starts in readonly mode by default. When readonly mode is active, it enforces these rules:

1. Read-only operations (list*, describe*, get*, etc.) — always allowed
2. Mutating operations with DryRun support (e.g., EC2 start/stop, Lambda invoke) — executed with DryRun=True to validate permissions without making changes
3. Mutating operations without DryRun (e.g., S3 put/delete, SSM put, SQS send) — blocked with a clear error message

This makes it safe to give Claude access to production AWS accounts for observation and troubleshooting.

Logging

All operations are logged in JSONL format to logs/aws_mcp.jsonl. Each line is a JSON object with fields:

{
  "timestamp": "2025-03-25T12:00:00.000000+00:00",
  "level": "INFO",
  "logger": "aws_mcp",
  "message": "Tool 'aws_ec2_describe_instances' completed successfully",
  "tool_name": "aws_ec2_describe_instances",
  "duration_ms": 342.15,
  "aws_profile": "production",
  "aws_region": "sa-east-1"
}

Telemetry (OpenTelemetry)

Every tool invocation creates an OpenTelemetry span with attributes like tool.name, aws.profile, aws.region, and duration_ms.

To export traces to an observability backend (Jaeger, Grafana Tempo, etc.):

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 .venv/bin/python main.py

Without the environment variable, tracing stays disabled.

Security Hooks

The repository ships with a versioned pre-push hook in .githooks/pre-push. Running ./setup.sh configures core.hooksPath automatically.

The hook runs scripts/security_scan.sh, which executes:

1. semgrep --config auto
2. gitleaks detect
3. trivy fs
4. bandit -r aws_mcp main.py
5. pip-audit

Required external binaries:

1. gitleaks
2. trivy

Python-based scanners are installed by default with pip install -e ".[dev]" during ./setup.sh. If you only want runtime dependencies, run INSTALL_DEV_TOOLS=0 ./setup.sh.

Project Structure

aws-mcp/
├── main.py                     # Entry point
├── aws_mcp/
│   ├── __init__.py             # App initialization
│   ├── server.py               # MCP server and tool dispatch
│   ├── config.py               # CLI argument parsing
│   ├── aws_client.py           # boto3 session management
│   ├── readonly_guard.py       # Readonly mode enforcement
│   ├── logging_config.py       # JSONL logging setup
│   ├── telemetry.py            # OpenTelemetry setup
│   └── tools/
│       ├── __init__.py         # Tool registry and loader
│       ├── profiles.py         # AWS profile / STS tools
│       ├── ec2.py              # EC2 tools
│       ├── s3.py               # S3 tools
│       ├── iam.py              # IAM tools
│       ├── lambda_tool.py      # Lambda tools
│       ├── cloudwatch.py       # CloudWatch Logs, Metrics & Alarms
│       ├── ecs.py              # ECS tools
│       ├── rds.py              # RDS tools
│       ├── dynamodb.py         # DynamoDB tools
│       ├── sqs.py              # SQS tools
│       ├── sns.py              # SNS tools
│       ├── ses.py              # SES tools
│       ├── ecr.py              # ECR tools
│       ├── elasticache.py      # ElastiCache (Redis/Memcached)
│       ├── elbv2.py            # ALB / NLB / Gateway LB
│       ├── autoscaling.py      # Auto Scaling Groups
│       ├── apigateway.py       # API Gateway v1 + v2
│       ├── cloudfront.py       # CloudFront
│       ├── route53.py          # Route53
│       ├── vpc.py              # VPC, subnets, gateways
│       ├── kms.py              # KMS keys and aliases
│       ├── acm.py              # ACM certificates
│       ├── cost_explorer.py    # Cost Explorer
│       ├── secretsmanager.py   # Secrets Manager
│       ├── ssm.py              # SSM Parameter Store
│       ├── cognito.py          # Cognito user pools
│       ├── eks.py              # EKS clusters and node groups
│       ├── kinesis.py          # Kinesis Data Streams
│       ├── firehose.py         # Kinesis Firehose
│       ├── stepfunctions.py    # Step Functions
│       ├── eventbridge.py      # EventBridge
│       ├── wafv2.py            # WAF v2
│       ├── guardduty.py        # GuardDuty
│       ├── securityhub.py      # Security Hub
│       ├── codepipeline.py     # CodePipeline
│       ├── codebuild.py        # CodeBuild
│       ├── codedeploy.py       # CodeDeploy
│       ├── athena.py           # Athena
│       ├── glue.py             # Glue
│       ├── mwaa.py             # MWAA (Managed Airflow)
│       ├── lakeformation.py    # Lake Formation
│       ├── cloudtrail.py       # CloudTrail
│       ├── cloudformation.py   # CloudFormation
│       ├── redshift.py         # Redshift
│       ├── efs.py              # EFS
│       ├── backup.py           # AWS Backup
│       ├── emr.py              # EMR
│       ├── sagemaker.py        # SageMaker
│       ├── opensearch.py       # OpenSearch
│       ├── documentdb.py       # DocumentDB
│       ├── memorydb.py         # MemoryDB
│       ├── organizations.py    # Organizations
│       ├── resourcegroups.py   # Resource Groups & Tag Manager
│       └── general.py          # General-purpose AWS executor
├── logs/                       # JSONL log output
├── pyproject.toml              # Package metadata and dependencies
├── setup.sh                    # Setup script
├── claude_desktop_config.example.json
├── LICENSE
└── README.md

License

BSD 3-Clause — see LICENSE for details.