aashari/mcp-server-aws-sso

aws_sso_login

Initiates the AWS SSO device authorization flow to obtain temporary credentials. This flow works as follows:

1. The tool generates a unique user verification code and authentication URL
2. A browser is opened to the AWS SSO login page (if launchBrowser: true)
3. You enter the verification code in the browser and complete the AWS SSO login
4. The tool receives and caches the token, valid for typically 8-12 hours
5. The cached token is then used by other AWS SSO tools without requiring repeated login

Browser launch behavior can be controlled with launchBrowser (default: true). When set to false, you must manually open the URL and enter the code.

Automatic polling for completion can be controlled with autoPoll (default: true). When set to false, the tool returns immediately after starting the flow, and you must use aws_sso_status to check completion.

Prerequisites:

• AWS SSO must be configured with a start URL and region (via AWS config file or environment variables)
• Browser access is required to complete the authentication flow
• You must have an AWS SSO account with appropriate permissions

Returns Markdown containing:

• Authentication status (already logged in, authentication started, or success)
• Session details (expiration time and duration if authenticated)
• Verification code and URL (if authentication is started)
• Browser launch status (if authentication is started)
• Next steps and usage guidance

aws_sso_status

Checks the current AWS SSO authentication status by verifying if a valid cached token exists and its expiration time.

This tool does NOT perform authentication itself - it only checks if you're already authenticated. If no valid token exists, it will instruct you to run aws_sso_login.

A valid cached token is required for all other AWS SSO commands to work. Use this tool to verify authentication status before using commands like aws_sso_ls_accounts or aws_sso_exec_command.

The tool checks:

• If a token exists in the cache
• If the token is still valid (not expired)
• When the token will expire (if valid)

Prerequisites:

• AWS SSO must be configured with a start URL and region (via AWS config file or environment variables)

Returns Markdown containing:

• Authentication status (authenticated or not)
• Session details (expiration time and duration if authenticated)
• Instructions for next steps based on the status

aws_sso_ls_accounts

Lists all AWS accounts and roles accessible to you through AWS SSO. This tool provides essential information needed for the aws_sso_exec_command tool.

The tool handles the following:

• Verifies you have a valid AWS SSO authentication token
• Fetches all accessible accounts with their IDs, names, and email addresses
• Retrieves all available roles for each account that you can assume
• Handles pagination internally to return the complete list in a single call
• Caches account and role information for better performance

Prerequisites:

• You MUST first authenticate successfully using aws_sso_login
• AWS SSO must be configured with a start URL and region
• Your AWS SSO permissions determine which accounts and roles are visible

Returns Markdown containing:

• Authentication session status and expiration
• Complete list of available accounts with their IDs, names, and emails
• Available roles for each account
• Usage instructions for executing commands with these accounts/roles
• Message if no accounts are found, with troubleshooting guidance

aws_sso_exec_command

Executes an AWS CLI command using temporary credentials obtained through AWS SSO. This tool enables you to run AWS CLI commands without manually configuring credentials.

How it works:

1. Verifies you have a valid AWS SSO authentication token
2. Obtains temporary credentials for the specified account and role
3. Sets up the environment with those credentials
4. Executes the AWS CLI command you specified
5. Caches credentials for the account/role combination for future use (typically valid for 1 hour)

Critical prerequisites:

• You MUST first authenticate using aws_sso_login to obtain a valid token
• AWS CLI MUST be installed on the system where the MCP server is running
• AWS SSO must be configured with a start URL and region
• You must have permissions to assume the specified role in the specified account

Required parameters:

• accountId: The 12-digit AWS account ID (get from aws_sso_ls_accounts)
• roleName: The IAM role name to assume (get from aws_sso_ls_accounts)
• command: The full AWS CLI command to execute (e.g., "aws s3 ls")

Optional parameters:

• region: AWS region to use for the command (defaults to configured region)

For complex commands with quoting, ensure proper escaping (e.g., "aws ec2 describe-instances --filters 'Name=tag:Name,Values=MyInstance'").

Returns comprehensive Markdown output that includes:

• Execution context (account, role, region)
• Command output (stdout)
• Error messages if any (stderr)
• Exit code (0 for success, non-zero for failure)
• Suggested alternative roles if permission errors occur

aws_sso_ec2_exec_command

Executes a shell command on an EC2 instance via AWS Systems Manager (SSM) using temporary credentials obtained through AWS SSO. This tool enables running commands on EC2 instances without requiring SSH access or opening inbound ports.

How it works:

1. Verifies you have a valid AWS SSO authentication token
2. Obtains temporary credentials for the specified account and role
3. Sends the command to the EC2 instance via SSM's RunShellScript document
4. Polls for command completion (up to 20 seconds)
5. Returns the command output and execution status

Critical prerequisites:

• You MUST first authenticate using aws_sso_login to obtain a valid token
• The EC2 instance MUST have the SSM Agent installed and running
• The instance MUST have an IAM role with the AmazonSSMManagedInstanceCore policy
• Your AWS role MUST have permissions for ssm:SendCommand and ssm:GetCommandInvocation
• AWS SSO must be configured with a start URL and region

Required parameters:

• instanceId: The EC2 instance ID (e.g., "i-1234567890abcdef0")
• accountId: The 12-digit AWS account ID (get from aws_sso_ls_accounts)
• roleName: The IAM role name to assume (get from aws_sso_ls_accounts)
• command: The shell command to execute (e.g., "ls -l", "whoami", "df -h")

Optional parameters:

• region: AWS region where the EC2 instance is located (defaults to configured region)

For complex commands with quoting, ensure proper escaping.

Returns comprehensive Markdown output that includes:

• Execution context (instance ID, account, role, region)
• Command that was executed
• Command output
• Error messages if any
• Troubleshooting guidance if SSM connection fails
• Suggested alternative roles if permission errors occur