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.

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

Enable AWS IAM Identity Center in your AWS account.
Set up your identity source (e.g., AWS SSO directory, Active Directory, or external IdP).
Configure permission sets and assign users to AWS accounts.
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.

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

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)

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

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

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.

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:

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

See CONTRIBUTING.md for details.

License

ISC License

AWS SSO

AWS SSO MCP Server

Why Use This Server?

What is MCP?

Prerequisites

Setup

Step 1: Configure AWS SSO

Step 2: Configure Credentials

Option A: MCP Config File (Recommended)

Option B: Environment Variables

Step 3: Install and Run

Quick Start with npx

Global Installation

Step 4: Connect to AI Assistant

MCP Tools

aws_sso_login

aws_sso_status

aws_sso_ls_accounts

aws_sso_exec_command

aws_sso_ec2_exec_command

Transport Modes

STDIO Transport (Default for MCP Clients)

HTTP Transport (Default for Server Mode)

Environment Variables

CLI Commands

Login

Execute AWS Commands

Execute EC2 Commands

Response Format

MCP Tool Response Example (aws_sso_exec_command)

Error Response Example

Development

Contributing

License

Related Servers

AlibabaCloud DevOps MCP

MCP DigitalOcean Integration

NASA MCP Server

Netbird

HuggingFace Spaces

Akamai MCP Server

Cloudflare to GitHub Backup MCP Server

Weather

Eyevinn Open Source Cloud

ONOS MCP Server