aws-mcp-server

Executes arbitrary AWS CLI commands through a JSON-RPC 2.0 MCP interface, translating AI assistant tool calls into containerized AWS CLI invocations with Unix pipe support. The aws_cli_pipeline tool accepts command strings, validates them against a security allowlist, executes them in an isolated subprocess, and returns formatted output optimized for AI consumption. Implements proper error handling, timeout management, and output buffering to prevent resource exhaustion.

Retrieves AWS CLI help documentation for services and commands via the aws_cli_help tool, parsing the native AWS CLI help output and formatting it for AI consumption. Supports three levels of documentation: service-level help (e.g., 'aws s3 help'), command-level help (e.g., 'aws s3 cp help'), and parameter details. The tool invokes 'aws <service> help' or 'aws <service> <command> help' subprocesses, captures and cleans the output, and returns structured documentation that AI assistants can use to understand available operations without external web lookups.

Manages server configuration through environment variables and optional config files, allowing users to customize behavior without code changes. Supports configuration of AWS profile, region, security allowlist rules, timeout settings, and logging levels. The configuration system reads from environment variables first, then falls back to config files, enabling both simple deployments (env vars only) and complex deployments (config files with overrides).

Provides native integration with Claude Desktop and Cursor through MCP protocol support, allowing these AI assistants to discover and invoke AWS CLI tools directly from their interfaces. The server implements MCP tool schemas that Claude and Cursor can parse and display as native tools, enabling seamless AWS operations without leaving the editor or chat interface. Configuration is handled through standard MCP client configuration files (claude_desktop_config.json for Claude, cursor_settings.json for Cursor).

Exposes AWS configuration and environment data as MCP Resources (read-only structured data), allowing AI assistants to query AWS profiles, regions, account information, and environment details without invoking CLI commands. Implements the MCP Resources protocol with URIs like 'aws://config/profiles', 'aws://config/regions', and 'aws://config/account-info', reading from ~/.aws/config, ~/.aws/credentials, and AWS SDK environment variables. Resources are served as structured text or JSON, enabling AI assistants to understand the user's AWS setup context before executing commands.

Validates AWS CLI commands before execution using a security layer that enforces an allowlist of safe operations and blocks potentially dangerous patterns (e.g., commands that delete resources, modify IAM policies, or access sensitive data). The security module inspects the parsed command structure, checks against configured allowlist rules, and rejects commands that don't match approved patterns. This prevents accidental or malicious execution of destructive AWS operations through the AI assistant interface, while still allowing a broad range of read and safe write operations.

Executes AWS CLI commands in an isolated Docker container environment rather than directly on the host system, providing process isolation, resource limits, and environment sandboxing. The server can be deployed as a Docker container with AWS credentials injected via environment variables or mounted volumes, ensuring that command execution is isolated from the host system and other processes. This architecture prevents credential leakage, limits resource consumption (CPU, memory, disk), and allows multiple isolated instances to run independently.

Provides pre-configured prompt templates that guide AI assistants through common AWS infrastructure workflows (e.g., launching EC2 instances, creating S3 buckets, configuring security groups). Templates are stored in prompts.py and include structured instructions, example commands, and validation steps that help AI assistants generate correct AWS CLI commands without trial-and-error. Templates can be injected into the AI assistant's context to improve command generation accuracy and reduce the need for manual correction.

Implements the Model Context Protocol (MCP) as a JSON-RPC 2.0 server that communicates with MCP-aware AI assistants (Claude Desktop, Cursor, Windsurf) via stdio or network sockets. The server.py module defines the MCP interface, tool schemas, and resource definitions, translating AI assistant tool calls into internal handler functions and returning results in MCP-compliant format. This allows any MCP-compatible AI assistant to discover and invoke AWS CLI tools without custom integration code.

Manages AWS credential contexts by reading from ~/.aws/config and ~/.aws/credentials files, allowing users to specify which AWS profile to use for command execution. The server can be configured to use a specific profile via environment variables or command-line arguments, and exposes available profiles through MCP Resources. This enables multi-account AWS operations where different commands can target different AWS accounts or credential sets without manual credential switching.

Exposes AWS regions and availability zone information through MCP Resources, allowing AI assistants to query available regions, default regions, and region-specific details (e.g., available services, AZ count). The server reads region information from AWS CLI metadata or environment variables and serves it as structured data through URIs like 'aws://config/regions' and 'aws://config/regions/{region}'. This enables AI assistants to understand regional constraints and make informed decisions about resource placement.

Processes AWS CLI command output and errors, formatting them for optimal AI assistant consumption by cleaning ANSI codes, structuring error messages, and handling both JSON and text output formats. The cli_executor.py module captures stdout and stderr, detects command failures, and returns formatted results that include exit codes, error context, and parsed output. This ensures AI assistants receive clear, actionable feedback about command success or failure without raw terminal output noise.