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.

• 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.

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.

• 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.

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).

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

export AWS_REGION=us-east-1
export AWS_SSO_START_URL=https://your-sso-portal.awsapps.com/start
export DEBUG=true

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

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

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

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

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.

{}

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

{}

{}

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

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

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

This server supports two transport modes for different integration scenarios:

• 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

• 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: https://localhost:3000/mcp
• Health check: https://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

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)

Authentication:

• AWS_SSO_START_URL: Your AWS SSO start URL
• AWS_SSO_REGION: Your AWS SSO region
• AWS_PROFILE: Your AWS profile name (optional)
• AWS_REGION: Your AWS region (optional)

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

mcp-aws-sso login

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

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

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

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

All responses are Markdown-formatted, including:

• Status: Success or error details.
• Context: Account, role, region, and execution time.
• Output: Command results or troubleshooting steps.

# 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*

# ❌ 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*

# 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

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 CONTRIBUTING.md for details.

ISC License