Server Aws Sso

Connect AI to Your AWS Resources

Transform how you manage and access your AWS infrastructure by connecting Claude, Cursor AI, and other AI assistants directly to your AWS accounts through AWS IAM Identity Center (formerly AWS SSO). Get instant access to your cloud resources, execute commands, and manage EC2 instances using natural language.

What You Can Do

✅ Ask AI about your AWS accounts: "Show me all my AWS accounts and available roles"
✅ Execute AWS commands: "List all S3 buckets in my production account"
✅ Manage EC2 instances: "Check the disk usage on server i-123456789"
✅ Access multi-account setups: "Switch to the staging account and describe the VPCs"
✅ Monitor resources: "Get the status of all running EC2 instances"
✅ Run shell commands: "Execute 'df -h' on my web server via SSM"

Perfect For

• DevOps Engineers managing multi-account AWS environments and infrastructure automation
• Cloud Architects needing quick access to resource information across AWS accounts
• Developers who want to check deployments and run AWS CLI commands through AI
• SRE Teams monitoring and troubleshooting AWS resources using natural language
• IT Administrators managing EC2 instances and executing remote commands securely
• Anyone who wants to interact with AWS using conversational AI

Quick Start

Get up and running in 2 minutes:

1. Get Your AWS SSO Setup

Set up AWS IAM Identity Center:

1. Enable AWS IAM Identity Center in your AWS account
2. Configure your identity source (AWS directory, Active Directory, or external IdP)
3. Set up permission sets and assign users to AWS accounts
4. Note your AWS SSO Start URL (e.g., https://your-company.awsapps.com/start)

2. Try It Instantly

# Set your AWS SSO configuration
export AWS_SSO_START_URL="https://your-company.awsapps.com/start"
export AWS_REGION="us-east-1"

# Start the authentication flow
npx -y @aashari/mcp-server-aws-sso login

# List your accessible accounts and roles
npx -y @aashari/mcp-server-aws-sso ls-accounts

# Execute an AWS command
npx -y @aashari/mcp-server-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name ReadOnly \
  --command "aws s3 ls"

Connect to AI Assistants

For Claude Desktop Users

Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):

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

Restart Claude Desktop, and you'll see "🔗 aws-sso" in the status bar.

For Other AI Assistants

Most AI assistants support MCP. Install the server globally:

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

Then configure your AI assistant to use the MCP server with STDIO transport.

Alternative: Configuration File

Create ~/.mcp/configs.json for system-wide configuration:

{
  "aws-sso": {
    "environments": {
      "AWS_SSO_START_URL": "https://your-company.awsapps.com/start",
      "AWS_REGION": "us-east-1",
      "DEBUG": "false"
    }
  }
}

Alternative config keys: The system also accepts "@aashari/mcp-server-aws-sso" or "mcp-server-aws-sso" instead of "aws-sso".

Real-World Examples

🔐 Authenticate and Explore

Ask your AI assistant:

• "Log into AWS SSO and show me my authentication status"
• "List all my AWS accounts and the roles I can assume"
• "Check if I'm still authenticated to AWS"
• "Show me which AWS accounts I have access to"

🛠️ Execute AWS Commands

Ask your AI assistant:

• "List all S3 buckets in my production account using the ReadOnly role"
• "Show me all running EC2 instances in the us-west-2 region"
• "Describe the VPCs in my staging AWS account"
• "Get the status of my RDS databases in account 123456789012"

🖥️ Manage EC2 Instances

Ask your AI assistant:

• "Check the disk usage on EC2 instance i-1234567890abcdef0"
• "Run 'uptime' on my web server via Systems Manager"
• "Execute 'systemctl status nginx' on instance i-abc123 in production"
• "Get memory usage from all my application servers"

🔍 Infrastructure Monitoring

Ask your AI assistant:

• "List all Lambda functions in my development account"
• "Show me the CloudFormation stacks in us-east-1"
• "Check the health of my load balancers"
• "Get the latest CloudWatch alarms that are in ALARM state"

🔄 Multi-Account Operations

Ask your AI assistant:

• "Switch to account 987654321098 with AdminRole and list all security groups"
• "Compare the running instances between staging and production accounts"
• "Check backup policies across all my AWS accounts"
• "Audit IAM users in the security account"

aws_sso_login

Basic Login:

{}

Custom Login Options:

{
  "launchBrowser": false
}

aws_sso_status

Check Authentication Status:

{}

aws_sso_ls_accounts

List All Accounts and Roles:

{}

aws_sso_exec_command

List S3 Buckets:

{
  "accountId": "123456789012", 
  "roleName": "ReadOnly",
  "command": "aws s3 ls"
}

Describe EC2 Instances in a Specific Region:

{
  "accountId": "123456789012",
  "roleName": "AdminRole",
  "command": "aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,State.Name,InstanceType]' --output table",
  "region": "us-west-2"
}

aws_sso_ec2_exec_command

Check System Resources:

{
  "instanceId": "i-0a69e80761897dcce",
  "accountId": "123456789012",
  "roleName": "InfraOps",
  "command": "uptime && df -h && free -m"
}

Transport Modes

This server supports two transport modes for different integration scenarios:

STDIO Transport (Default for MCP Clients)

• Traditional subprocess communication via stdin/stdout
• Ideal for local AI assistant integrations (Claude Desktop, Cursor AI)
• Uses pipe-based communication for direct MCP protocol exchange

# Run with STDIO transport (default for AI assistants)
TRANSPORT_MODE=stdio npx @aashari/mcp-server-aws-sso

# Using npm scripts (after installation)
npm run mcp:stdio

HTTP Transport (Default for Server Mode)

• Modern HTTP-based transport with Server-Sent Events (SSE)
• Supports multiple concurrent connections
• Better for web-based integrations and development
• Runs on port 3000 by default (configurable via PORT env var)
• Endpoint: http://localhost:3000/mcp
• Health check: http://localhost:3000/

# Run with HTTP transport (default when no CLI args)
TRANSPORT_MODE=http npx @aashari/mcp-server-aws-sso

# Using npm scripts (after installation)
npm run mcp:http

# Test with MCP Inspector
npm run mcp:inspect

Environment Variables

Transport Configuration:

• TRANSPORT_MODE: Set to stdio or http (default: http for server mode, stdio for MCP clients)
• PORT: HTTP server port (default: 3000)
• DEBUG: Enable debug logging (default: false)

AWS Configuration:

• AWS_SSO_START_URL: Your AWS IAM Identity Center start URL (e.g., https://your-org.awsapps.com/start)
• AWS_SSO_REGION or AWS_REGION: AWS region for SSO authentication (e.g., us-east-1)
• AWS_PROFILE: AWS profile name (optional, for CLI compatibility)

Available Tools

When integrated with AI assistants via MCP, the following tools are available:

Authentication Tools

• aws_sso_login: Initiates AWS SSO device authorization flow

  • Parameters: launchBrowser (optional, boolean, default: true)
  • Opens browser automatically for authentication
  • Handles device authorization code flow
  • Caches tokens for subsequent operations

• aws_sso_status: Checks current authentication status

  • No parameters required
  • Returns session details and expiration time
  • Verifies cached token validity

Account Management Tools

• aws_sso_ls_accounts: Lists all accessible AWS accounts and roles
  • No parameters required
  • Shows account IDs, names, emails, and available roles
  • Essential for discovering which accounts/roles you can use

Command Execution Tools

• aws_sso_exec_command: Executes AWS CLI commands with SSO credentials

  • Required: accountId, roleName, command
  • Optional: region
  • Automatically obtains and caches temporary credentials
  • Supports any AWS CLI command

• aws_sso_ec2_exec_command: Executes shell commands on EC2 instances via SSM

  • Required: instanceId, accountId, roleName, command
  • Optional: region
  • No SSH access required (uses AWS Systems Manager)
  • Instance must have SSM Agent installed

CLI Commands

All tools are also available as CLI commands using kebab-case. Run --help for details (e.g., mcp-aws-sso login --help).

• login: Authenticates via AWS SSO (--no-launch-browser). Ex: mcp-aws-sso login.
• status: Checks authentication status (no options). Ex: mcp-aws-sso status.
• ls-accounts: Lists accounts/roles (no options). Ex: mcp-aws-sso ls-accounts.
• exec-command: Runs AWS CLI command (--account-id, --role-name, --command, --region). Ex: mcp-aws-sso exec-command --account-id 123456789012 --role-name ReadOnly --command "aws s3 ls".
• ec2-exec-command: Runs shell command on EC2 (--instance-id, --account-id, --role-name, --command, --region). Ex: mcp-aws-sso ec2-exec-command --instance-id i-0a69e80761897dcce --account-id 123456789012 --role-name InfraOps --command "uptime".

Login

Standard Login (launches browser and polls automatically):

mcp-aws-sso login

Login without Browser Launch:

mcp-aws-sso login --no-launch-browser

Execute AWS Commands

List S3 Buckets:

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name ReadOnly \
  --command "aws s3 ls"

List EC2 Instances with Specific Region:

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name AdminRole \
  --region us-west-2 \
  --command "aws ec2 describe-instances --output table"

Execute EC2 Commands

Check System Resources:

mcp-aws-sso ec2-exec-command \
  --instance-id i-0a69e80761897dcce \
  --account-id 123456789012 \
  --role-name InfraOps \
  --command "uptime && df -h && free -m"

Troubleshooting

"Authentication failed" or "Token expired"

1. Re-authenticate with AWS SSO:

   # Test your SSO configuration
   npx -y @aashari/mcp-server-aws-sso login

   Copy to clipboard

2. Check your AWS SSO configuration:

   • Verify your AWS_SSO_START_URL is correct (should be your organization's SSO portal)
   • Ensure your AWS_REGION matches your SSO region configuration

3. Verify your SSO setup:

   • Make sure you can access the SSO portal in your browser
   • Check that your AWS account assignments are active

"Account not found" or "Role not found"

1. Check available accounts and roles:

   # List all accessible accounts
   npx -y @aashari/mcp-server-aws-sso ls-accounts

   Copy to clipboard

2. Verify account ID format:

   • Account ID should be exactly 12 digits
   • Use the exact account ID from the ls-accounts output

3. Check role permissions:

   • Make sure you have permission to assume the specified role
   • Use the exact role name from your permission sets

"AWS CLI not found" or Command execution errors

…