AWS Model Context Protocol (MCP) Bridge for Amazon Web Services

A custom implementation of the Model Context Protocol (MCP) server designed to allow advanced conversational agents, such as Claude, direct, natural-language access to your AWS estate. This tool effectively serves as an enhanced, conversational replacement for native tools like Amazon Q.

Core Capabilities

• Interpret and execute AWS management tasks described in plain English.
• Support for managing credentials across multiple defined AWS profiles.
• Compatibility with resources deployed across various AWS regions.
• Secure, local execution leveraging existing, configured AWS access keys.

Operational Flow

(Workflow section omitted for brevity)

Prerequisites for Deployment

• A functional installation of Python.
• The Claude Desktop application.
• Valid AWS authentication material securely set up in the default location (~/.aws/).

Setup Instructions

1. Clone the repository source code:

bash git clone https://github.com/yourusername/aws-mcp cd aws-mcp

1. Install the required Python MCP server package:

bash pip install -e .

Command-Line Utility Usage

The AWS MCP package also exposes functionality directly through the command line:

bash

Display supported actions

python -m aws_mcp --help

Enumerate configured AWS credential sets

python -m aws_mcp list-credentials

Designate a specific profile for subsequent operations

python -m aws_mcp select-profile myprofile

Initiate an AWS operation via NL command

python -m aws_mcp run-aws-code "retrieve the state of all EC2 instances"

Request human-readable output formatting

python -m aws_mcp --format pretty list-credentials

Note: If 'python' is not in your system PATH, substitute it with the absolute path to your Python interpreter.

Integration with Claude Desktop

1. Navigate to the Settings panel within the Claude desktop client and select Developer -> Edit Config.

2. Incorporate the following configuration block into your claude_desktop_config.json file:

{ "mcpServers": { "aws-mcp": { "command": "/path/to/your/python", "args": ["/path/to/your/aws-mcp/run_aws_mcp.py"] } } }

Crucial: Verify that /path/to/your/python matches the output of the which python command in your terminal. Crucial: Ensure /path/to/your/aws-mcp/run_aws_mcp.py points to the exact location of the main execution script.

1. Reload or restart the Claude desktop application.

2. Begin interaction by either specifying a context or issuing a directive, such as:

   • "Report my available AWS profiles."
   • "List every running EC2 instance across all regions."
   • "Provide a summary of S3 storage utilization."
   • "Identify all Lambda deployments within the us-east-1 region."
   • "Detail the structure of my ECS clusters and associated services."

Diagnostics and Logging

To monitor server activity, review the latest entries in the designated log file:

bash tail -n 50 -f ~/Library/Logs/Claude/mcp-server-aws-mcp.log

Alternative log path for general MCP activity:

tail -n 50 -f ~/Library/Logs/Claude/mcp.log

Future Enhancements

• [ ] Implementation of Multi-Factor Authentication (MFA) handling.
• [ ] Introduction of an SSO credential caching mechanism to optimize token refresh timing.

Support and Contribution

For technical inquiries, feature suggestions, or to report issues regarding the AWS MCP integration: - Initiate a new issue on the project's GitHub repository. - Contact the maintainer via email: arun.sanna@outlook.com

Refer to CONTRIBUTING.md for guidelines on how to contribute code or documentation.

Deep Dive: AWS Interaction Mechanics

The AWS MCP leverages the boto3 library for dynamic execution of cloud management tasks. It is engineered to:

1. Intelligently parse user input, whether idiomatic or structured, to determine the requisite AWS service and corresponding API call.
2. Automatically invoke the necessary boto3 function.
3. Present the results in a well-structured, tabular format whenever feasible.
4. Manage and report exceptions encountered during remote execution in a user-friendly manner.

Recognized Services (Partial List)

The built-in parser has the capability to interface with any service exposed via the boto3 SDK, including but not limited to:

• S3 (Simple Storage Service)
• EC2 (Elastic Compute Cloud)
• Lambda (Serverless Compute)
• IAM (Identity and Access Management)
• DynamoDB (NoSQL Database)
• RDS (Relational Database Service)
• CloudFormation (Infrastructure as Code)
• CloudWatch (Monitoring and Metrics)
• SNS (Simple Notification Service)
• SQS (Simple Queue Service)
• KMS (Key Management Service)
• Secrets Manager
• SSM (Systems Manager)
• Route53 (DNS)
• CloudFront (CDN)
• Elastic Beanstalk
• API Gateway
• ECS (Elastic Container Service)
• STS (Security Token Service)
• Cognito
• CodeBuild
• CodeCommit
• CodePipeline
• Organizations
• GuardDuty
• ...and numerous others.

WIKIPEDIA: The concept of cloud computing, as defined by the ISO, refers to "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand."

== NIST Essential Characteristics (2011) == The National Institute of Standards and Technology (NIST) established five foundational attributes for cloud systems:

On-demand self-service: Consumers can provision computing capacity (e.g., server time, storage) independently, without requiring human intervention from the provider. Broad network access: Services are accessible across the network via standard protocols, supporting diverse client platforms (mobile, desktop, etc.). Resource pooling: The provider's infrastructure is aggregated to serve multiple tenants through a multi-tenant architecture, with resources dynamically allocated based on demand. Rapid elasticity: Capabilities can be scaled up or down quickly—often automatically—to match fluctuating workload requirements, frequently appearing limitless to the end-user. Measured service: Resource consumption (e.g., storage, processing time, bandwidth) is automatically tracked, monitored, and reported transparently for both provider and consumer.

These definitions were subsequently refined by the International Organization for Standardization (ISO) by 2023.

== Genesis of Cloud Concepts ==

Early conceptual foundations trace back to the 1960s with the rise of time-sharing systems and remote job entry (RJE). During this period, computing power was centralized in mainframes managed by operators.

The term 'cloud' for virtualized resources gained traction in 1994 when General Magic utilized it to describe the interconnected 'places' accessible to agents in their Telescript framework. The metaphor is often attributed to David Hoffman, drawing from its established use in telecommunications diagrams. The phrase 'cloud computing' entered broader corporate discourse in 1996 via a business plan drafted by Compaq Computer Corporation outlining future internet computing strategies.