# 🏗️ AWS Well-Architected MCP Server
A powerful Model Context Protocol (MCP) server that provides seamless integration with AWS Well-Architected Framework for AI assistants like GitHub Copilot, AWS Q, Cursor, and other modern IDEs.
## 🚀 Features
- **Complete AWS Well-Architected Integration**: Access all major Well-Architected Framework capabilities
- **AI Assistant Ready**: Works with GitHub Copilot, AWS Q, Cursor, and other MCP-compatible tools
- **Easy Configuration**: Simple setup for any IDE or AI assistant
- **Secure AWS Access**: Uses your existing AWS credentials and profiles
- **Rich Functionality**:
- List and explore Well-Architected lenses
- Manage workloads and reviews
- Access improvement recommendations
- Generate reports
- Track milestones
## 📋 Prerequisites
- Python 3.11+
- AWS CLI configured (`aws configure`)
- Active AWS credentials with Well-Architected permissions
- An IDE or AI assistant that supports MCP (VS Code, Cursor, etc.)
## 🛠️ Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install wellarchitected-mcp-server
```
### Option 2: Install with uvx (Preferred for AI assistants)
```bash
uvx wellarchitected-mcp-server@latest
```
### Option 3: Development Installation
```bash
git clone <repository-url>
cd wellarchitected-mcp-server
pip install -e .
```
## ⚙️ Configuration
### AWS Credentials Setup
Ensure your AWS credentials are configured:
```bash
aws configure
# or
export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1
```
### Required AWS Permissions
Your AWS credentials need the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"wellarchitected:List*",
"wellarchitected:Get*",
"wellarchitected:Create*",
"wellarchitected:Update*"
],
"Resource": "*"
}
]
}
```
## 🔧 IDE and AI Assistant Configuration
### GitHub Copilot (VS Code)
Add to your `.vscode/settings.json`:
```json
{
"github.copilot.chat.experimental.modelContextProtocol.servers": {
"aws-wellarchitected": {
"command": "uvx",
"args": ["wellarchitected-mcp-server@latest"],
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1"
}
}
}
}
```
### AWS Q (if supporting MCP)
```json
{
"mcp_servers": {
"aws-wellarchitected": {
"command": "wellarch-mcp",
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1"
}
}
}
}
```
### Cursor IDE
Add to your Cursor configuration:
```json
{
"mcp": {
"servers": {
"aws-wellarchitected": {
"command": "uvx",
"args": ["wellarchitected-mcp-server@latest"],
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1"
}
}
}
}
}
```
### Other IDEs
For any MCP-compatible tool, use:
```json
{
"command": "wellarch-mcp",
"args": ["start-server"],
"env": {
"AWS_PROFILE": "your-profile",
"AWS_REGION": "your-region"
}
}
```
## 🚦 Quick Start
### 1. Test Your Connection
```bash
wellarch-mcp test-connection
```
### 2. Start the Server Manually
```bash
wellarch-mcp start-server --host 0.0.0.0 --port 8000
```
### 3. Use with Your AI Assistant
Once configured, you can ask your AI assistant questions like:
- "List my AWS Well-Architected workloads"
- "Show me the lenses available in Well-Architected"
- "Create a new workload for my production environment"
- "What are the improvement recommendations for workload xyz?"
- "Generate a lens review report for my workload"
## 🛠️ Available Tools
The MCP server provides these tools to AI assistants:
| Tool | Description |
|------|-------------|
| `list_lenses` | List available Well-Architected lenses |
| `get_lens_details` | Get detailed information about a specific lens |
| `list_workloads` | List your Well-Architected workloads |
| `get_workload_details` | Get detailed workload information |
| `create_workload` | Create a new workload |
| `list_answers` | List answers for a workload review |
| `get_answer_details` | Get detailed answer information |
| `list_milestones` | List workload milestones |
| `get_lens_review_report` | Generate a lens review report |
| `list_improvement_summaries` | Get improvement recommendations |
## 🧪 Development and Testing
### Local Development
```bash
# Clone the repository
git clone <repository-url>
cd wellarchitected-mcp-server
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
isort .
# Type checking
mypy .
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `AWS_PROFILE` | AWS profile to use | `default` |
| `AWS_REGION` | AWS region | `us-east-1` |
| `FASTMCP_LOG_LEVEL` | Logging level | `INFO` |
## 📝 Example Usage
Here are some example interactions you can have with your AI assistant:
### List Workloads
> "Show me all my Well-Architected workloads"
### Create a Workload
> "Create a new Well-Architected workload called 'MyApp Production' for a production environment in us-east-1 and us-west-2"
### Get Improvement Recommendations
> "What improvements are recommended for workload abc123?"
### Generate Report
> "Generate a lens review report for my workload xyz789"
## 🔒 Security Considerations
- Always use IAM roles with least-privilege access
- Never hardcode AWS credentials
- Use AWS profiles for different environments
- Monitor MCP server logs for security events
- Keep the server updated to the latest version
## 🤝 Contributing
We welcome contributions! Please see our contributing guidelines for details.
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 🆘 Support
- 📚 Check the [AWS Well-Architected documentation](https://docs.aws.amazon.com/wellarchitected/)
- 🐛 Report issues on GitHub
- 💬 Join our community discussions
## 🚀 What's Next?
- Integration with more AI assistants
- Enhanced reporting capabilities
- Multi-account support
- Custom lens support
- Automated workload analysis
---
Made with ❤️ for the AWS and AI community
Raw data
{
"_id": null,
"home_page": null,
"name": "wellarchitected-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Pratik Raut <pratik@example.com>",
"keywords": "mcp, model-context-protocol, aws, well-architected, ai, assistant, copilot",
"author": null,
"author_email": "Pratik Raut <pratik@example.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/be/91872e063550c0f933354d0f6e9c9484ccc3ba896f4605a63405c744ca7e/wellarchitected_mcp_server-0.1.3.tar.gz",
"platform": null,
"description": "# \ud83c\udfd7\ufe0f AWS Well-Architected MCP Server\n\nA powerful Model Context Protocol (MCP) server that provides seamless integration with AWS Well-Architected Framework for AI assistants like GitHub Copilot, AWS Q, Cursor, and other modern IDEs.\n\n## \ud83d\ude80 Features\n\n- **Complete AWS Well-Architected Integration**: Access all major Well-Architected Framework capabilities\n- **AI Assistant Ready**: Works with GitHub Copilot, AWS Q, Cursor, and other MCP-compatible tools\n- **Easy Configuration**: Simple setup for any IDE or AI assistant\n- **Secure AWS Access**: Uses your existing AWS credentials and profiles\n- **Rich Functionality**: \n - List and explore Well-Architected lenses\n - Manage workloads and reviews\n - Access improvement recommendations\n - Generate reports\n - Track milestones\n\n## \ud83d\udccb Prerequisites\n\n- Python 3.11+\n- AWS CLI configured (`aws configure`)\n- Active AWS credentials with Well-Architected permissions\n- An IDE or AI assistant that supports MCP (VS Code, Cursor, etc.)\n\n## \ud83d\udee0\ufe0f Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install wellarchitected-mcp-server\n```\n\n### Option 2: Install with uvx (Preferred for AI assistants)\n\n```bash\nuvx wellarchitected-mcp-server@latest\n```\n\n### Option 3: Development Installation\n\n```bash\ngit clone <repository-url>\ncd wellarchitected-mcp-server\npip install -e .\n```\n\n## \u2699\ufe0f Configuration\n\n### AWS Credentials Setup\n\nEnsure your AWS credentials are configured:\n\n```bash\naws configure\n# or\nexport AWS_PROFILE=your-profile\nexport AWS_REGION=us-east-1\n```\n\n### Required AWS Permissions\n\nYour AWS credentials need the following permissions:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"wellarchitected:List*\",\n \"wellarchitected:Get*\",\n \"wellarchitected:Create*\",\n \"wellarchitected:Update*\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n## \ud83d\udd27 IDE and AI Assistant Configuration\n\n### GitHub Copilot (VS Code)\n\nAdd to your `.vscode/settings.json`:\n\n```json\n{\n \"github.copilot.chat.experimental.modelContextProtocol.servers\": {\n \"aws-wellarchitected\": {\n \"command\": \"uvx\",\n \"args\": [\"wellarchitected-mcp-server@latest\"],\n \"env\": {\n \"AWS_PROFILE\": \"default\",\n \"AWS_REGION\": \"us-east-1\"\n }\n }\n }\n}\n```\n\n### AWS Q (if supporting MCP)\n\n```json\n{\n \"mcp_servers\": {\n \"aws-wellarchitected\": {\n \"command\": \"wellarch-mcp\",\n \"env\": {\n \"AWS_PROFILE\": \"default\",\n \"AWS_REGION\": \"us-east-1\"\n }\n }\n }\n}\n```\n\n### Cursor IDE\n\nAdd to your Cursor configuration:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"aws-wellarchitected\": {\n \"command\": \"uvx\",\n \"args\": [\"wellarchitected-mcp-server@latest\"],\n \"env\": {\n \"AWS_PROFILE\": \"default\",\n \"AWS_REGION\": \"us-east-1\"\n }\n }\n }\n }\n}\n```\n\n### Other IDEs\n\nFor any MCP-compatible tool, use:\n\n```json\n{\n \"command\": \"wellarch-mcp\",\n \"args\": [\"start-server\"],\n \"env\": {\n \"AWS_PROFILE\": \"your-profile\",\n \"AWS_REGION\": \"your-region\"\n }\n}\n```\n\n## \ud83d\udea6 Quick Start\n\n### 1. Test Your Connection\n\n```bash\nwellarch-mcp test-connection\n```\n\n### 2. Start the Server Manually\n\n```bash\nwellarch-mcp start-server --host 0.0.0.0 --port 8000\n```\n\n### 3. Use with Your AI Assistant\n\nOnce configured, you can ask your AI assistant questions like:\n\n- \"List my AWS Well-Architected workloads\"\n- \"Show me the lenses available in Well-Architected\"\n- \"Create a new workload for my production environment\"\n- \"What are the improvement recommendations for workload xyz?\"\n- \"Generate a lens review report for my workload\"\n\n## \ud83d\udee0\ufe0f Available Tools\n\nThe MCP server provides these tools to AI assistants:\n\n| Tool | Description |\n|------|-------------|\n| `list_lenses` | List available Well-Architected lenses |\n| `get_lens_details` | Get detailed information about a specific lens |\n| `list_workloads` | List your Well-Architected workloads |\n| `get_workload_details` | Get detailed workload information |\n| `create_workload` | Create a new workload |\n| `list_answers` | List answers for a workload review |\n| `get_answer_details` | Get detailed answer information |\n| `list_milestones` | List workload milestones |\n| `get_lens_review_report` | Generate a lens review report |\n| `list_improvement_summaries` | Get improvement recommendations |\n\n## \ud83e\uddea Development and Testing\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd wellarchitected-mcp-server\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack .\nisort .\n\n# Type checking\nmypy .\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AWS_PROFILE` | AWS profile to use | `default` |\n| `AWS_REGION` | AWS region | `us-east-1` |\n| `FASTMCP_LOG_LEVEL` | Logging level | `INFO` |\n\n## \ud83d\udcdd Example Usage\n\nHere are some example interactions you can have with your AI assistant:\n\n### List Workloads\n> \"Show me all my Well-Architected workloads\"\n\n### Create a Workload\n> \"Create a new Well-Architected workload called 'MyApp Production' for a production environment in us-east-1 and us-west-2\"\n\n### Get Improvement Recommendations\n> \"What improvements are recommended for workload abc123?\"\n\n### Generate Report\n> \"Generate a lens review report for my workload xyz789\"\n\n## \ud83d\udd12 Security Considerations\n\n- Always use IAM roles with least-privilege access\n- Never hardcode AWS credentials\n- Use AWS profiles for different environments\n- Monitor MCP server logs for security events\n- Keep the server updated to the latest version\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our contributing guidelines for details.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## \ud83c\udd98 Support\n\n- \ud83d\udcda Check the [AWS Well-Architected documentation](https://docs.aws.amazon.com/wellarchitected/)\n- \ud83d\udc1b Report issues on GitHub\n- \ud83d\udcac Join our community discussions\n\n## \ud83d\ude80 What's Next?\n\n- Integration with more AI assistants\n- Enhanced reporting capabilities\n- Multi-account support\n- Custom lens support\n- Automated workload analysis\n\n---\n\nMade with \u2764\ufe0f for the AWS and AI community\n",
"bugtrack_url": null,
"license": null,
"summary": "AWS Well-Architected MCP Server for AI assistants like GitHub Copilot, AWS Q, and more",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/your-username/wellarchitected-mcp-server/issues",
"Documentation": "https://github.com/your-username/wellarchitected-mcp-server#readme",
"Homepage": "https://github.com/your-username/wellarchitected-mcp-server",
"Repository": "https://github.com/your-username/wellarchitected-mcp-server.git"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" aws",
" well-architected",
" ai",
" assistant",
" copilot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e535f2bbad07187eacb59aa18ae3279a25b77a7833447f9fc019add54112184a",
"md5": "0400ea2ad37bebf314c81397801552f0",
"sha256": "99836542032bfa06f03b248b219b47449bfc8f8d9bd9cf2f5f088af45f6e0191"
},
"downloads": -1,
"filename": "wellarchitected_mcp_server-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0400ea2ad37bebf314c81397801552f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11149,
"upload_time": "2025-07-10T13:44:40",
"upload_time_iso_8601": "2025-07-10T13:44:40.275592Z",
"url": "https://files.pythonhosted.org/packages/e5/35/f2bbad07187eacb59aa18ae3279a25b77a7833447f9fc019add54112184a/wellarchitected_mcp_server-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ddbe91872e063550c0f933354d0f6e9c9484ccc3ba896f4605a63405c744ca7e",
"md5": "61175864ff167be1d11aab23dfd6427b",
"sha256": "6075a89df4509a2dbd820dcd9a1fa1f26f41f12614726ee809d8dafd79093db8"
},
"downloads": -1,
"filename": "wellarchitected_mcp_server-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "61175864ff167be1d11aab23dfd6427b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11589,
"upload_time": "2025-07-10T13:44:41",
"upload_time_iso_8601": "2025-07-10T13:44:41.247780Z",
"url": "https://files.pythonhosted.org/packages/dd/be/91872e063550c0f933354d0f6e9c9484ccc3ba896f4605a63405c744ca7e/wellarchitected_mcp_server-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 13:44:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-username",
"github_project": "wellarchitected-mcp-server",
"github_not_found": true,
"lcname": "wellarchitected-mcp-server"
}
JSON
