# AWS Security Group Management System
[](https://pypi.org/project/awswhitelist-mcp/)
[](https://pypi.org/project/awswhitelist-mcp/)
[](https://opensource.org/licenses/MIT)
A comprehensive solution for managing AWS EC2 Security Group rules with environment variable configuration, Model Context Protocol (MCP) server integration, and secure credential management.
## 🚀 Features
- **Environment-based Configuration**: Secure credential management using `.env` files
- **MCP Server Integration**: Compatible with Claude Desktop and other MCP clients
- **Flexible Rule Management**: Add, list, and manage security group rules
- **Audit Logging**: Track all changes with timestamps and user attribution
- **Description Formatting**: Standardized rule descriptions with timestamps
- **Validation**: IP address and port validation with configurable rules
- **JSON-based Interface**: Easy integration with automation tools
## 📁 Project Structure
```
D:\dev2\awswhitelist2\
├── .env # Environment configuration (create from .env.example)
├── .env.example # Template for environment variables
├── .gitignore # Git ignore rules
├── config_manager.py # Centralized configuration management
├── test_environment.py # Environment setup verification
├── setup_env.bat # Windows setup script
├── ENV_README.md # Environment variables documentation
│
├── simple_test/ # Core scripts
│ ├── test_aws_access.py # Test AWS connectivity
│ ├── add_sg_rule_json.py # Original JSON-based script
│ ├── add_sg_rule_env.py # Environment-aware version
│ └── ... # Other utility scripts
│
└── mcp_server/ # MCP server implementation
├── server.py # Original Python MCP server
├── server_env.py # Environment-aware MCP server
├── index.ts # TypeScript MCP server
└── claude_desktop_config_env.json # Claude Desktop config
```
## 🔧 Quick Start
### Claude Desktop Integration
This MCP server is fully compatible with Claude Desktop. See [CLAUDE_DESKTOP_SETUP.md](CLAUDE_DESKTOP_SETUP.md) for installation instructions.
## 🔧 Quick Start
### 1. Setup Environment
**Windows:**
```cmd
setup_env.bat
```
**Manual:**
```bash
cp .env.example .env
# Edit .env with your AWS credentials
```
### 2. Install Dependencies
```bash
pip install python-dotenv boto3 mcp
```
### 3. Test Configuration
```bash
python test_environment.py
```
### 4. Test AWS Connection
```bash
python simple_test/test_aws_access.py
```
## 🔐 Environment Variables
Key environment variables (see `.env.example` for full list):
```env
# AWS Credentials
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here
AWS_DEFAULT_REGION=us-east-1
# Default Security Group
DEFAULT_SECURITY_GROUP_ID=sg-0f0df629567eb6344
DEFAULT_SECURITY_GROUP_NAME=whm-dev
# Description Format
DESCRIPTION_PREFIX=auto
DESCRIPTION_SEPARATOR=-
DESCRIPTION_TIMESTAMP_FORMAT=%Y%m%d-%H%M
```
## 📝 Usage Examples
### Command Line Usage
**Add a security group rule:**
```bash
python simple_test/add_sg_rule_env.py '{
"UserName": "john_doe",
"UserIP": "203.0.113.45",
"Port": "8080",
"SecurityGroupID": "sg-0f0df629567eb6344",
"ResourceName": "WebApp"
}'
```
**With dry run:**
```bash
python simple_test/add_sg_rule_env.py --dry-run '{...}'
```
**Using different environment file:**
```bash
python simple_test/add_sg_rule_env.py --env-file .env.production '{...}'
```
### MCP Server with Claude Desktop
1. **Configure Claude Desktop:**
- Copy configuration from `mcp_server/claude_desktop_config_env.json`
- Add to `%APPDATA%\Claude\claude_desktop_config.json`
2. **Restart Claude Desktop**
3. **Use in Claude:**
```
Add IP 192.168.1.100 to security group sg-0f0df629567eb6344 on port 8080
```
## 🛡️ Security Best Practices
1. **Never commit `.env` files** - Use `.env.example` as template
2. **Use IAM roles** when running on AWS infrastructure
3. **Rotate credentials** regularly
4. **Minimal permissions** - Only grant required EC2 permissions:
- `ec2:DescribeSecurityGroups`
- `ec2:AuthorizeSecurityGroupIngress`
- `ec2:RevokeSecurityGroupIngress`
## 📊 Description Format
Rules are created with standardized descriptions:
```
{ResourceName} - {Port}-auto-{UserName}-YYYYMMDD-HHMM
```
Example: `WebApp - 8080-auto-john_doe-20250711-1430`
## 🧪 Testing
**Test environment setup:**
```bash
python test_environment.py
```
**Test AWS connectivity:**
```bash
python simple_test/test_aws_access.py
```
**Test MCP server locally:**
```bash
python mcp_server/server_env.py
```
## 🔍 Troubleshooting
### Common Issues
1. **Module not found:**
```bash
pip install python-dotenv boto3 mcp
```
2. **AWS credentials error:**
- Check `.env` file exists and has correct values
- Verify no extra spaces or quotes
- Test with AWS CLI: `aws sts get-caller-identity`
3. **Permission denied:**
- Ensure IAM user has required EC2 permissions
- Check security group exists and is accessible
### Debug Mode
Set environment variable:
```env
MCP_LOG_LEVEL=DEBUG
```
## 📚 Advanced Usage
### Multiple Environments
```bash
# Development
ENV_FILE=.env.dev python simple_test/add_sg_rule_env.py ...
# Production
ENV_FILE=.env.prod python simple_test/add_sg_rule_env.py ...
```
### Programmatic Usage
```python
from config_manager import get_config
import boto3
# Load configuration
config = get_config()
aws_config = config.get_aws_client_config()
# Create EC2 client
ec2 = boto3.client('ec2', **aws_config)
# Use configuration values
description = config.format_description("App", "8080", "user")
```
## 🤝 Contributing
1. Create feature branch
2. Make changes
3. Test thoroughly
4. Submit pull request
## 📄 License
This project is licensed under the MIT License.
## 🆘 Support
- Check [ENV_README.md](ENV_README.md) for environment configuration
- Review [TODO.md](simple_test/TODO.md) for roadmap
- See [FUTURE.md](simple_test/FUTURE.md) for enhancement ideas
---
**Note:** Remember to keep your AWS credentials secure and never commit them to version control!
Raw data
{
"_id": null,
"home_page": "https://github.com/dbbuilder/awswhitelist2",
"name": "awswhitelist-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "aws, security-group, mcp, model-context-protocol, whitelist, ip-management",
"author": "DBBuilder",
"author_email": "dbbuilderio@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/35/ad/e28c56c62f0c542bfa83f01d805dd6eef6d509e556015da64f283aca4d3e/awswhitelist_mcp-1.1.10.tar.gz",
"platform": null,
"description": "# AWS Security Group Management System\r\n\r\n[](https://pypi.org/project/awswhitelist-mcp/)\r\n[](https://pypi.org/project/awswhitelist-mcp/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA comprehensive solution for managing AWS EC2 Security Group rules with environment variable configuration, Model Context Protocol (MCP) server integration, and secure credential management.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Environment-based Configuration**: Secure credential management using `.env` files\r\n- **MCP Server Integration**: Compatible with Claude Desktop and other MCP clients\r\n- **Flexible Rule Management**: Add, list, and manage security group rules\r\n- **Audit Logging**: Track all changes with timestamps and user attribution\r\n- **Description Formatting**: Standardized rule descriptions with timestamps\r\n- **Validation**: IP address and port validation with configurable rules\r\n- **JSON-based Interface**: Easy integration with automation tools\r\n\r\n## \ud83d\udcc1 Project Structure\r\n\r\n```\r\nD:\\dev2\\awswhitelist2\\\r\n\u251c\u2500\u2500 .env # Environment configuration (create from .env.example)\r\n\u251c\u2500\u2500 .env.example # Template for environment variables\r\n\u251c\u2500\u2500 .gitignore # Git ignore rules\r\n\u251c\u2500\u2500 config_manager.py # Centralized configuration management\r\n\u251c\u2500\u2500 test_environment.py # Environment setup verification\r\n\u251c\u2500\u2500 setup_env.bat # Windows setup script\r\n\u251c\u2500\u2500 ENV_README.md # Environment variables documentation\r\n\u2502\r\n\u251c\u2500\u2500 simple_test/ # Core scripts\r\n\u2502 \u251c\u2500\u2500 test_aws_access.py # Test AWS connectivity\r\n\u2502 \u251c\u2500\u2500 add_sg_rule_json.py # Original JSON-based script\r\n\u2502 \u251c\u2500\u2500 add_sg_rule_env.py # Environment-aware version\r\n\u2502 \u2514\u2500\u2500 ... # Other utility scripts\r\n\u2502\r\n\u2514\u2500\u2500 mcp_server/ # MCP server implementation\r\n \u251c\u2500\u2500 server.py # Original Python MCP server\r\n \u251c\u2500\u2500 server_env.py # Environment-aware MCP server\r\n \u251c\u2500\u2500 index.ts # TypeScript MCP server\r\n \u2514\u2500\u2500 claude_desktop_config_env.json # Claude Desktop config\r\n```\r\n\r\n## \ud83d\udd27 Quick Start\r\n\r\n### Claude Desktop Integration\r\n\r\nThis MCP server is fully compatible with Claude Desktop. See [CLAUDE_DESKTOP_SETUP.md](CLAUDE_DESKTOP_SETUP.md) for installation instructions.\r\n\r\n## \ud83d\udd27 Quick Start\r\n\r\n### 1. Setup Environment\r\n\r\n**Windows:**\r\n```cmd\r\nsetup_env.bat\r\n```\r\n\r\n**Manual:**\r\n```bash\r\ncp .env.example .env\r\n# Edit .env with your AWS credentials\r\n```\r\n\r\n### 2. Install Dependencies\r\n\r\n```bash\r\npip install python-dotenv boto3 mcp\r\n```\r\n\r\n### 3. Test Configuration\r\n\r\n```bash\r\npython test_environment.py\r\n```\r\n\r\n### 4. Test AWS Connection\r\n\r\n```bash\r\npython simple_test/test_aws_access.py\r\n```\r\n\r\n## \ud83d\udd10 Environment Variables\r\n\r\nKey environment variables (see `.env.example` for full list):\r\n\r\n```env\r\n# AWS Credentials\r\nAWS_ACCESS_KEY_ID=your_access_key_here\r\nAWS_SECRET_ACCESS_KEY=your_secret_key_here\r\nAWS_DEFAULT_REGION=us-east-1\r\n\r\n# Default Security Group\r\nDEFAULT_SECURITY_GROUP_ID=sg-0f0df629567eb6344\r\nDEFAULT_SECURITY_GROUP_NAME=whm-dev\r\n\r\n# Description Format\r\nDESCRIPTION_PREFIX=auto\r\nDESCRIPTION_SEPARATOR=-\r\nDESCRIPTION_TIMESTAMP_FORMAT=%Y%m%d-%H%M\r\n```\r\n\r\n## \ud83d\udcdd Usage Examples\r\n\r\n### Command Line Usage\r\n\r\n**Add a security group rule:**\r\n```bash\r\npython simple_test/add_sg_rule_env.py '{\r\n \"UserName\": \"john_doe\",\r\n \"UserIP\": \"203.0.113.45\",\r\n \"Port\": \"8080\",\r\n \"SecurityGroupID\": \"sg-0f0df629567eb6344\",\r\n \"ResourceName\": \"WebApp\"\r\n}'\r\n```\r\n\r\n**With dry run:**\r\n```bash\r\npython simple_test/add_sg_rule_env.py --dry-run '{...}'\r\n```\r\n\r\n**Using different environment file:**\r\n```bash\r\npython simple_test/add_sg_rule_env.py --env-file .env.production '{...}'\r\n```\r\n\r\n### MCP Server with Claude Desktop\r\n\r\n1. **Configure Claude Desktop:**\r\n - Copy configuration from `mcp_server/claude_desktop_config_env.json`\r\n - Add to `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n\r\n2. **Restart Claude Desktop**\r\n\r\n3. **Use in Claude:**\r\n ```\r\n Add IP 192.168.1.100 to security group sg-0f0df629567eb6344 on port 8080\r\n ```\r\n\r\n## \ud83d\udee1\ufe0f Security Best Practices\r\n\r\n1. **Never commit `.env` files** - Use `.env.example` as template\r\n2. **Use IAM roles** when running on AWS infrastructure\r\n3. **Rotate credentials** regularly\r\n4. **Minimal permissions** - Only grant required EC2 permissions:\r\n - `ec2:DescribeSecurityGroups`\r\n - `ec2:AuthorizeSecurityGroupIngress`\r\n - `ec2:RevokeSecurityGroupIngress`\r\n\r\n## \ud83d\udcca Description Format\r\n\r\nRules are created with standardized descriptions:\r\n```\r\n{ResourceName} - {Port}-auto-{UserName}-YYYYMMDD-HHMM\r\n```\r\n\r\nExample: `WebApp - 8080-auto-john_doe-20250711-1430`\r\n\r\n## \ud83e\uddea Testing\r\n\r\n**Test environment setup:**\r\n```bash\r\npython test_environment.py\r\n```\r\n\r\n**Test AWS connectivity:**\r\n```bash\r\npython simple_test/test_aws_access.py\r\n```\r\n\r\n**Test MCP server locally:**\r\n```bash\r\npython mcp_server/server_env.py\r\n```\r\n\r\n## \ud83d\udd0d Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Module not found:**\r\n ```bash\r\n pip install python-dotenv boto3 mcp\r\n ```\r\n\r\n2. **AWS credentials error:**\r\n - Check `.env` file exists and has correct values\r\n - Verify no extra spaces or quotes\r\n - Test with AWS CLI: `aws sts get-caller-identity`\r\n\r\n3. **Permission denied:**\r\n - Ensure IAM user has required EC2 permissions\r\n - Check security group exists and is accessible\r\n\r\n### Debug Mode\r\n\r\nSet environment variable:\r\n```env\r\nMCP_LOG_LEVEL=DEBUG\r\n```\r\n\r\n## \ud83d\udcda Advanced Usage\r\n\r\n### Multiple Environments\r\n\r\n```bash\r\n# Development\r\nENV_FILE=.env.dev python simple_test/add_sg_rule_env.py ...\r\n\r\n# Production \r\nENV_FILE=.env.prod python simple_test/add_sg_rule_env.py ...\r\n```\r\n\r\n### Programmatic Usage\r\n\r\n```python\r\nfrom config_manager import get_config\r\nimport boto3\r\n\r\n# Load configuration\r\nconfig = get_config()\r\naws_config = config.get_aws_client_config()\r\n\r\n# Create EC2 client\r\nec2 = boto3.client('ec2', **aws_config)\r\n\r\n# Use configuration values\r\ndescription = config.format_description(\"App\", \"8080\", \"user\")\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Create feature branch\r\n2. Make changes\r\n3. Test thoroughly\r\n4. Submit pull request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\n## \ud83c\udd98 Support\r\n\r\n- Check [ENV_README.md](ENV_README.md) for environment configuration\r\n- Review [TODO.md](simple_test/TODO.md) for roadmap\r\n- See [FUTURE.md](simple_test/FUTURE.md) for enhancement ideas\r\n\r\n---\r\n\r\n**Note:** Remember to keep your AWS credentials secure and never commit them to version control!\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for AWS Security Group IP whitelisting with stateless credential handling",
"version": "1.1.10",
"project_urls": {
"Homepage": "https://github.com/dbbuilder/awswhitelist2"
},
"split_keywords": [
"aws",
" security-group",
" mcp",
" model-context-protocol",
" whitelist",
" ip-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79874b2ef612b5ffa262d64ef0c9f58691cdf036c914ee58787231d6fd18b71b",
"md5": "c1920c4ba9b7f834b3865111fb526dbe",
"sha256": "9a2744c93f90d4e6460adb7c8b00b3f244af7585aa700017c7e65ef50f552d52"
},
"downloads": -1,
"filename": "awswhitelist_mcp-1.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1920c4ba9b7f834b3865111fb526dbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22862,
"upload_time": "2025-07-17T07:47:50",
"upload_time_iso_8601": "2025-07-17T07:47:50.836183Z",
"url": "https://files.pythonhosted.org/packages/79/87/4b2ef612b5ffa262d64ef0c9f58691cdf036c914ee58787231d6fd18b71b/awswhitelist_mcp-1.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "35ade28c56c62f0c542bfa83f01d805dd6eef6d509e556015da64f283aca4d3e",
"md5": "0695e34484ae591f681ba7d94810ac74",
"sha256": "023109351fd9ab21430fadd70cf9723d9c0a5c5e6de921adbc1600036a1bf415"
},
"downloads": -1,
"filename": "awswhitelist_mcp-1.1.10.tar.gz",
"has_sig": false,
"md5_digest": "0695e34484ae591f681ba7d94810ac74",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23544,
"upload_time": "2025-07-17T07:47:51",
"upload_time_iso_8601": "2025-07-17T07:47:51.746564Z",
"url": "https://files.pythonhosted.org/packages/35/ad/e28c56c62f0c542bfa83f01d805dd6eef6d509e556015da64f283aca4d3e/awswhitelist_mcp-1.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 07:47:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dbbuilder",
"github_project": "awswhitelist2",
"github_not_found": true,
"lcname": "awswhitelist-mcp"
}
JSON
