aws-security

AWS Security MCP provides an AI-assisted interface to analyze and monitor your AWS security posture through natural language questions. It integrates with GuardDuty, SecurityHub, Access Analyzer, and Athena-backed log analytics to deliver findings, topology maps, blast-radius assessments, and cross-account visibility across your AWS Organization. You can ask it to scan resources across accounts, identify misconfigurations, retrieve security findings, and generate recommendations in plain English. The server is designed to work with Claude-compatible MCP clients and accepts queries via an MCP proxy interface, returning structured security insights that can be used to drive automation or human review. Use the included tooling to query resources, map network topology, and perform security reviews across accounts and regions using simple natural language prompts.

Prerequisites

• Python 3.11 or newer
• Access to a Python environment (virtualenv/uv recommended)
• AWS credentials with required permissions as described in the README (SecurityAudit managed policy recommended)

Local installation (recommended)

1. Clone the repository

   git clone https://github.com/groovyBugify/aws-security-mcp.git cd aws-security-mcp

2. Create and activate a Python virtual environment (example using uv)

   uv venv source .venv/bin/activate

3. Install dependencies

   uv pip install -r requirements.txt

4. Run the MCP server locally

   uv run aws_security_mcp.py

   Note: If you are using the Python module approach, you can also run:

   python -m aws_security_mcp

5. Configure your MCP client (Claude Desktop or compatible client) Output should be accessible via the MCP proxy URL (e.g., http://localhost:8000/sse)

Prerequisites recap in brief

• A compatible MCP client (Claude Desktop, Cline, etc.)
• AWS IAM permissions as described in the README (SecurityAudit policy recommended)
• Proper AWS credentials configured locally or via environment variables

Tips and common considerations:

• Ensure your AWS credentials have the required cross-account and data access permissions described in the AWS requirements section, especially the SecurityAudit policy for basic functionality.
• If you enable Athena-based log analysis, update the placeholders in the permissions to reflect your actual S3 buckets and data catalogs.
• When running in ECS or Docker, ensure port mappings align with your client (default expectation is port 8000 for the MCP proxy service).
• For large token payloads, consider using a capable MCP client configuration or higher plan as noted in the README.
• If you encounter permission errors, verify that your IAM role or user has the necessary cross-account and data access permissions and that the policy boundaries are correctly set.