mcp-server-aws-sso

mcp-server-aws-sso

1
cloud_platformsai_chatbotos_automation

AWS SSO MCP Server is designed to facilitate secure interaction between AI systems and AWS resources through SSO. It offers features such as multi-account support and AWS CLI compatibility, providing seamless and secure credential management.

AWS SSO MCP Server

A Node.js/TypeScript Model Context Protocol (MCP) server for AWS Single Sign-On (SSO). Enables AI systems (e.g., LLMs like Claude or Cursor AI) to securely interact with AWS resources by initiating SSO login, listing accounts/roles, and executing AWS CLI commands using temporary credentials.

NPM Version Build Status

Why Use This Server?

  • Seamless SSO Integration: Authenticate via AWS SSO device flow, avoiding long-term credential exposure.
  • Secure Credential Management: Uses temporary credentials with automatic rotation.
  • Multi-Account Support: Discover and manage all AWS accounts/roles accessible via SSO.
  • AWS CLI Compatibility: Execute any AWS CLI command securely through AI or CLI interfaces.
  • Automated Authentication: Simplifies login with browser launch and token polling.

What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements MCP for AWS SSO, enabling AI assistants to manage AWS resources programmatically.

Prerequisites

  • Node.js (>=18.x): Download
  • AWS CLI v2: Install
  • AWS Account with SSO Configured: Ensure AWS IAM Identity Center is enabled with permission sets and user assignments.

Setup

Step 1: Configure AWS SSO

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

Step 2: Configure Credentials

Option A: MCP Config File (Recommended)

Edit or create ~/.mcp/configs.json:

{
	"aws-sso": {
		"environments": {
			"AWS_REGION": "us-east-1",
			"AWS_SSO_START_URL": "https://your-sso-portal.awsapps.com/start",
			"DEBUG": "true"
		}
	}
}
Option B: Environment Variables
export AWS_REGION=us-east-1
export AWS_SSO_START_URL=https://your-sso-portal.awsapps.com/start
export DEBUG=true

Step 3: Install and Run

Quick Start with npx
npx -y @aashari/mcp-server-aws-sso login
Global Installation
npm install -g @aashari/mcp-server-aws-sso
mcp-aws-sso login

Step 4: Connect to AI Assistant

Configure your MCP-compatible client (e.g., Claude, Cursor AI):

{
	"mcpServers": {
		"aws-sso": {
			"command": "npx",
			"args": ["-y", "@aashari/mcp-server-aws-sso"]
		}
	}
}

MCP Tools

MCP tools use snake_case names, camelCase parameters, and return Markdown-formatted responses.

  • aws_sso_login: Initiates AWS SSO device authorization (launchBrowser: bool opt, autoPoll: bool opt). Use: Log in to AWS SSO.
  • aws_sso_status: Checks SSO authentication status (no params). Use: Verify authentication.
  • aws_sso_ls_accounts: Lists accessible AWS accounts/roles (no params). Use: Discover accounts.
  • aws_sso_exec_command: Executes AWS CLI command with temporary credentials (accountId: str req, roleName: str req, command: str req, region: str opt). Use: Run aws s3 ls.
  • aws_sso_ec2_exec_command: Runs shell commands on EC2 via SSM (instanceId: str req, accountId: str req, roleName: str req, command: str req, region: str opt). Use: Check EC2 disk space.
MCP Tool Examples (Click to expand)

aws_sso_login

Basic Login:

{}

Custom Login Options:

{
  "launchBrowser": false,
  "autoPoll": true
}

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"
}

CLI Commands

CLI commands use kebab-case. Run --help for details (e.g., mcp-aws-sso login --help).

  • login: Authenticates via AWS SSO (--no-launch-browser, --no-auto-poll). 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".
CLI Command Examples (Click to expand)

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"

Response Format

All responses are Markdown-formatted, including:

  • Status: Success or error details.
  • Context: Account, role, region, and execution time.
  • Output: Command results or troubleshooting steps.
Response Format Examples (Click to expand)

MCP Tool Response Example (aws_sso_exec_command)

# AWS SSO: Command Result

**Account/Role:** 123456789012/ReadOnly
**Region:** us-east-1 (Default: ap-southeast-1)

## Command

	aws s3 ls

## Output

	2023-01-15 08:42:53 my-bucket-1
	2023-05-22 14:18:19 my-bucket-2
	2024-02-10 11:05:37 my-logs-bucket

*Executed: 2025-05-19 06:21:49 UTC*

Error Response Example

# ❌ AWS SSO: Command Error

**Account/Role:** 123456789012/ReadOnly
**Region:** us-east-1 (Default: ap-southeast-1)

## Command
	
	aws s3api get-object --bucket restricted-bucket --key secret.txt output.txt

## Error: Permission Denied
The role `ReadOnly` does not have permission to execute this command.

## Error Details

	An error occurred (AccessDenied) when calling the GetObject operation: Access Denied

### Troubleshooting

#### Available Roles
- AdminAccess
- PowerUserAccess
- S3FullAccess

Try executing the command again using one of the roles listed above that has appropriate permissions.

*Executed: 2025-05-19 06:17:49 UTC*

Development

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

# Install dependencies
npm install

# Run in development mode
npm run dev:server

# Run tests
npm test

Contributing

Contributions are welcome! Please:

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/xyz).
  3. Commit changes (git commit -m "Add xyz feature").
  4. Push to the branch (git push origin feature/xyz).
  5. Open a pull request.

See for details.

License