Bridging Conversational AI with Your Amazon Cloud Infrastructure

Revolutionize your interaction model with AWS resources by establishing a direct, secure conduit from large language models (like Claude or Cursor) to your cloud accounts, authenticated via AWS Single Sign-On (IAM Identity Center). Obtain immediate access to inventory data, dispatch operational commands, and manage infrastructure components using natural language instructions.

Core Capabilities for AI Interaction

✅ Inventory Inquiry: "Enumerate all accessible AWS organizational units and the associated permission sets." ✅ CLI Command Dispatch: "Execute 'aws ec2 describe-vpcs --output json' within my primary development account." ✅ Instance Management: "Query the system uptime metrics for EC2 identifier i-123456789." ✅ Cross-Account Context Switching: "Transition context to the production workspace and retrieve database configuration details." ✅ Resource Health Check: "Report the current operational status for all active virtual machines." ✅ Remote Shell Execution: "Fire the command 'yum update -y' against my staging server fleet utilizing SSM Agent."

Optimal Use Cases

• Infrastructure Automation Specialists: Streamlining operations across sprawling, multi-account AWS organizational structures.
• Cloud Solution Architects: Rapid, on-demand retrieval of configuration metadata spanning disparate cloud workspaces.
• Software Developers: Interfacing with AWS APIs and CLI tooling directly through conversational prompts.
• Site Reliability Engineers (SRE): Proactive diagnostics and incident response leveraging natural language interaction with cloud telemetry.
• System Administrators: Secure remote execution and lifecycle management of EC2 virtual machines.
• Any User: Seeking an intuitive, natural-language interface for interacting with the AWS ecosystem.

Rapid Deployment Guide

Achieve operational status in under 120 seconds:

1. AWS IAM Identity Center Prerequisite

Ensure your AWS Identity Center environment is configured: 1. Activate AWS IAM Identity Center within the target management account. 2. Integrate your authoritative identity provider (e.g., Azure AD, Okta, or native AWS Directory Service). 3. Define granular permission sets and map users/groups to specific AWS accounts. 4. Capture the AWS SSO Portal Start URL (e.g., https://your-organization.awsapps.com/sso/start).

2. Immediate Operational Testing

bash

Configure necessary environmental variables pointing to your SSO instance

export AWS_SSO_START_URL="https://your-organization.awsapps.com/start" export AWS_REGION="us-west-2"

Initiate the secure authentication handshake

npx -y @aashari/mcp-server-aws-sso login

Query for accessible cloud accounts and assumed roles

npx -y @aashari/mcp-server-aws-sso ls-accounts

Invoke an AWS operational command

npx -y @aashari/mcp-server-aws-sso exec-command \ --account-id 987654321098 \ --role-name SecurityAuditor \ --command "aws sts get-caller-identity"

Integration with AI Frontends

For Claude Desktop Integrations

Augment your local configuration file (~/.claude/claude_desktop_config.json):

{ "mcpServers": { "aws-sso-identity": { "command": "npx", "args": ["-y", "@aashari/mcp-server-aws-sso"], "env": { "AWS_SSO_START_URL": "https://your-organization.awsapps.com/start", "AWS_REGION": "us-west-2" } } } }

Upon restarting the Claude client, a new communication endpoint, "🔗 aws-sso-identity," will appear in the control panel.

For Other MCP-Compliant Platforms

Global installation is recommended for broadest utility:

bash npm install -g @aashari/mcp-server-aws-sso

Configure your chosen AI interface to utilize the server via its standard input/output (STDIO) communication channel.

System-Wide Configuration File

Alternatively, define settings globally via ~/.mcp/configs.json:

{ "aws-sso-identity": { "environments": { "AWS_SSO_START_URL": "https://your-organization.awsapps.com/start", "AWS_REGION": "us-west-2", "DEBUG_LOGGING": "false" } } }

Alias Note: The configuration key can also reference the package name directly ("@aashari/mcp-server-aws-sso").

Real-World Interaction Scenarios

🔐 Session Initialization and Context Verification

Prompt your AI agent with: - "Initiate the AWS SSO authentication sequence and report the current session metadata." - "Display a comprehensive list of all obtainable AWS accounts and their assumed roles." - "Confirm the validity and expiry of the current authentication context." - "Provide a catalog of all cloud accounts visible through the current Identity Center configuration."

🛠️ Remote AWS API Execution

Request actions like: - "Audit all S3 storage buckets in the production workspace utilizing the AuditorRole." - "Retrieve the detailed configuration of all running EC2 virtual machines within the eu-central-1 zone." - "Outline the Virtual Private Cloud (VPC) topology in the designated staging account." - "Fetch the current operational status for all managed RDS database instances under account 987654321098."

🖥️ EC2 System-Level Interactions

Instruct the AI to execute on specific instances: - "Determine the current filesystem utilization statistics for instance i-0a69e80761897dcce." - "Fire the command 'systemctl restart httpd' on my primary web node via SSM Run Command." - "Execute 'cat /proc/cpuinfo' on instance i-abc123 in the development environment." - "Aggregate memory utilization metrics across the entire fleet of application servers."

🔍 Cloud Resource Monitoring

Ask for status updates: - "List every deployed AWS Lambda function across my development accounts." - "Fetch the status of all active CloudFormation stacks deployed in us-east-1." - "Assess the operational health of all associated Elastic Load Balancers." - "Retrieve the most recent CloudWatch alarms currently reporting an ALARM state."

🔄 Multi-Workspace Operations

Orchestrate across boundaries: - "Switch context to account 112233445566 using the GlobalAdminRole and list all associated security groups." - "Perform a comparison of running compute instance counts between staging and production tenants." - "Audit the established backup policies across the entire set of connected AWS tenants." - "Review and report on all IAM users within the dedicated security operations account."

Protocol Method Signatures (JSON Invocation Examples)

### `aws_sso_login` (Authentication Initiation) **Default Invocation:** {} **Disabling Browser Launch:** { "launchBrowser": false } ### `aws_sso_status` (Context Verification) **Check Authentication State:** {} ### `aws_sso_list_workspaces` (Inventory Retrieval) **Fetch Account/Role Inventory:** {} ### `aws_sso_invoke_cli` (General AWS API Call) **Listing S3 Assets:** { "accountId": "123456789012", "roleName": "ReadOnly", "command": "aws s3 ls" } **Region-Scoped EC2 Query:** { "accountId": "123456789012", "roleName": "Administrator", "command": "aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,State.Name,InstanceType]' --output table", "region": "eu-west-1" } ### `aws_sso_run_ssm_command` (Remote Instance Operations) **System Diagnostics:** { "instanceId": "i-0a69e80761897dcce", "accountId": "123456789012", "roleName": "OpsEngineer", "command": "uptime && df -h && free -m" }

Communication Transport Mechanisms

This server supports dual modes for integration flexibility:

STDIO Transport (Standard for MCP Clients)

• Utilizes conventional pipe-based communication via standard input/output streams.
• Optimal for tightly coupled, local agent execution environments (e.g., Claude Desktop).

bash

Explicitly force STDIO mode for local execution

TRANSPORT_MODE=stdio npx @aashari/mcp-server-aws-sso

Using installed package script

npm run mcp:stdio

HTTP Transport (Default for Standalone Server Mode)

• Employs modern HTTP/HTTPS protocols, leveraging Server-Sent Events (SSE) for push capabilities.
• Designed for asynchronous interactions, supporting multiple concurrent client sessions.
• Default listening port is 3000 (adjustable via PORT environment variable).
• Primary API Endpoint: http://localhost:3000/mcp
• System Health Check: http://localhost:3000/

bash

Launch as a persistent HTTP service

TRANSPORT_MODE=http npx @aashari/mcp-server-aws-sso

Using npm scripts

npm run mcp:http

Utility for inspecting HTTP traffic

npm run mcp:inspect

Essential Environment Variables

Transport Settings: - TRANSPORT_MODE: Set to stdio or http (Default: http for server launch, stdio for client context). - PORT: Defines the network port for HTTP operation (Default: 3000). - DEBUG: Toggles verbose diagnostic output (Boolean).

AWS Authentication Context: - AWS_SSO_START_URL: Mandatory entry point URL for Identity Center. - AWS_SSO_REGION: The AWS region where your Identity Center is provisioned. - AWS_PROFILE: Optional override for specific AWS CLI profile configuration. - AWS_REGION: Default region for subsequent AWS CLI operations if not specified in the command JSON.

Command Line Interface (CLI) Reference

CLI operations adhere to kebab-case conventions. Use the --help flag for method-specific parameter details (e.g., mcp-aws-sso login --help).

• login: Triggers SSO authentication sequence (--no-launch-browser suppresses browser opening). Usage: mcp-aws-sso login.
• status: Reports current token validity (No arguments required). Usage: mcp-aws-sso status.
• ls-accounts: Enumerates accessible AWS workspaces and roles (No arguments required). Usage: mcp-aws-sso ls-accounts.
• exec-command: Executes arbitrary AWS CLI statements (--account-id, --role-name, --command, --region are key parameters). Usage example: mcp-aws-sso exec-command --account-id 123456789012 --role-name Auditor --command "aws sts get-caller-identity".
• ec2-exec-command: Executes OS-level commands on target instances via SSM (--instance-id, --account-id, --role-name, --command, --region). Usage example: mcp-aws-sso ec2-exec-command --instance-id i-0a69e80761897dcce --account-id 123456789012 --role-name SysAdmin --command "uptime".

CLI Command Walkthroughs

### Session Login **Standard Browser-Assisted Login:** bash mcp-aws-sso login **Non-Interactive Login Attempt:** bash mcp-aws-sso login --no-launch-browser ### AWS API Command Invocation **S3 Bucket Listing:** bash mcp-aws-sso exec-command \ --account-id 123456789012 \ --role-name ReadOnly \ --command "aws s3 ls" **Region-Specific EC2 Inventory:** bash mcp-aws-sso exec-command \ --account-id 123456789012 \ --role-name PowerUser \ --region ap-southeast-2 \ --command "aws ec2 describe-instances --output table" ### SSM Instance Command Execution **System Resource Check:** bash mcp-aws-sso ec2-exec-command \ --instance-id i-0a69e80761897dcce \ --account-id 123456789012 \ --role-name InfraOps \ --command "uptime && df -h && free -m"

Diagnostic and Error Resolution

⚠️ Encountering "Authentication Failure" or "Token Invalidation"

1. Re-establish Session: Force a fresh authentication pass: bash npx -y @aashari/mcp-server-aws-sso login

2. Validate Configuration Inputs:

3. Confirm the AWS_SSO_START_URL precisely matches your organization's Identity Center access portal.

4. Ensure AWS_SSO_REGION aligns with the region hosting your Identity Center configuration.

5. Browser Verification:

6. Manually navigate to the SSO Start URL to confirm accessibility and valid user session status.

⚠️ "Target Account/Role Not Resolvable"

1. Review Accessible Entities: bash npx -y @aashari/mcp-server-aws-sso ls-accounts

2. ID Format Confirmation:

3. Account identifiers must strictly adhere to the 12-digit standard shown in the listing output.

4. Permission Set Validation:

5. Verify that the assigned permission set grants the ability to assume the role name specified in the request.

⚠️ "AWS CLI Command Execution Errors"

1. Prerequisite Check: AWS CLI v2 Installation:
2. Installation is mandatory for API interaction tooling. Consult the Official AWS CLI Installation Guide.

3. Confirm that the aws executable is reachable system-wide (i.e., present in the PATH).

4. Independent CLI Verification: bash aws --version aws sts get-caller-identity

⚠️ "SSM Command Delivery Failure on EC2"

1. Instance Prerequisites:
2. The target EC2 instance must have the SSM Agent installed and confirmed to be running.

3. The instance IAM profile requires the AmazonSSMManagedInstanceCore managed policy attached.

4. Assumed Role Permissions:

5. The role used for execution must possess the ssm:SendCommand and ssm:GetCommandInvocation permissions.

6. Confirm the EC2 instance is in a 'running' state.

7. SSM Connectivity Test: bash # Verify the instance can communicate with the SSM service endpoint npx -y @aashari/mcp-server-aws-sso exec-command \ --account-id YOUR_ACCOUNT \ --role-name YOUR_ROLE \ --command "aws ssm get-parameters-by-path --path /"

Claude Desktop Configuration Problems

1. Always perform a complete restart of the Claude application after modifying the configuration structure.
2. Visually confirm the presence of the connection indicator: "🔗 aws-sso-identity".
3. Double-check the configuration file path for your operating system:
4. macOS: ~/.claude/claude_desktop_config.json
5. Windows: %APPDATA%\Claude\claude_desktop_config.json

Seeking Advanced Support

If standard troubleshooting fails: 1. Execute a minimal, verifiable command to isolate the failure point. 2. Search existing resolutions on the Official GitHub Repository Issues Tracker. 3. Submit a detailed new issue, including environment specifications and full error tracebacks.

Frequently Encountered Queries

What credential access permissions are mandatory?

For SSO Environment Setup: - An active AWS SSO account linked to IAM Identity Center. - Administrator clearance to define and assign permission sets. - Necessary permissions granted by your IAM administrator to access target AWS environments.

For SSM Remote Operations: - The assumed role requires fine-grained permissions for SSM interaction (ssm:SendCommand, etc.). - Target EC2 instances must possess the AmazonSSMManagedInstanceCore IAM policy.

Can this utility manage credentials across multiple distinct AWS Organizations?

Presently, the persistent configuration maps to a singular AWS SSO Start URL. Managing multiple independent organizations necessitates either reconfiguring the environment variables between sessions or leveraging distinct deployment instances of the server for each organization.

What is the standard validity period for retrieved SSO session tokens?

AWS SSO session lifetimes are generally set between 8 to 12 hours. The temporary credentials generated for specific account/role assumptions usually expire after 60 minutes. The MCP server actively manages token refresh and secure credential caching to ensure seamless operation.

Which AI frameworks are compatible with this protocol implementation?

This server adheres strictly to the Model Context Protocol (MCP) specification, supporting: - Claude Desktop Client (Primary Target) - Cursor AI Development Environment - Continue.dev - Numerous other MCP-enabled artificial intelligence platforms.

How is data privacy and security maintained?

Security is paramount: - Local Execution: All authentication processes and command relay occur exclusively on your host machine. - Credential Ownership: Leverages your existing, protected AWS SSO credentials. - No Data Exfiltration: Sensitive session data is never transmitted to external servers. - Principle of Least Privilege: Only accesses resources explicitly permitted by your assumed IAM roles. - Ephemeral Credentials: Utilizes short-lived session tokens that automatically become invalid.

Is prior installation of the AWS CLI mandatory?

While the core authentication and inventory fetching tools operate independently, the aws_sso_exec_command functionality critically relies on having AWS CLI v2 installed and accessible in the execution path for constructing and parsing API calls.

Does this tool interact with standard AWS CLI profile files (~/.aws/credentials)?

No. This server establishes and maintains its own secure, temporary credential store derived directly from the SSO login flow, bypassing reliance on static profiles defined in the standard AWS CLI configuration directories.

Protocol Output Schema Examples

### MCP Tool Success Output (`aws_sso_invoke_cli`) markdown # AWS SSO: Command Execution Report **Context**: 987654321098/SecurityAuditor **Region**: ap-northeast-1 (Defaulted: us-east-1) ## Executed Operation aws s3 ls ## Standard Output Stream 2023-07-01 10:00:00 global-config-bucket 2024-01-20 15:30:11 compliance-data-archive 2025-04-11 09:12:45 log-retention-store *Invocation Time: 2025-05-19 06:21:49 UTC* ### MCP Tool Failure Report Example markdown # 🛑 AWS SSO: Operation Failure Notice **Context**: 123456789012/ReadOnly **Region**: us-east-1 (Defaulted: ap-southeast-1) ## Executed Operation aws s3api delete-object --bucket sensitive-data-store --key old_backup.zip ## Error Classification: Authorization Violation Attempted operation is prohibited for the currently assumed role (`ReadOnly`). ## Detailed API Error Message An error occurred (AccessDenied) when calling the DeleteObject operation: Access Denied to resource 'sensitive-data-store'. ### Remediation Suggestions #### Identified Permitted Roles - IAMFullAccess - S3Admin - SecurityReadOnly Re-submit the request using a role possessing explicit write/delete permissions for S3 resources. *Invocation Time: 2025-05-19 06:17:49 UTC*

Developer Contribution Guide

bash

Obtain the source repository

git clone https://github.com/aashari/mcp-server-aws-sso.git cd mcp-server-aws-sso

Install requisite packages for development

npm install

Initiate development watch-mode execution

npm run dev:server

Execute comprehensive unit and integration test suite

npm test

Support Channels

If you require assistance beyond the self-help documentation:

1. Review Diagnostics Above: Check the comprehensive troubleshooting matrix first.
2. Visit the Source Repository: Comprehensive documentation and roadmap details are maintained at: github.com/aashari/mcp-server-aws-sso
3. File a Bug Report: Use the official tracker for reproducible errors: GitHub Issues
4. General Inquiries: Open a discussion thread for feature suggestions or general architecture questions.

---

Engineered with precision for enterprise DevOps teams seeking to seamlessly integrate conversational AI into their AWS operational framework.