AWS SSO MCP Server

This project provides a Model Context Protocol (MCP) server that connects AI assistants (like Anthropic's Claude, Cursor AI, or other MCP-compatible clients) to AWS services using Single Sign-On (SSO) authentication. It enables AI models to interact with and manage your AWS resources through structured tools with simplified authentication.

Overview

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI systems to securely and contextually connect with external tools and data sources.

This server implements MCP specifically for AWS SSO, bridging your AI assistants with AWS services using secure, temporary credentials.

Why Use This Server?

• Seamless AWS SSO Integration: Connect to AWS with secure single sign-on, avoiding the need to manage or expose long-term credentials in your AI interactions.

• Secure Credential Management: Uses temporary credentials acquired through AWS SSO, following AWS security best practices with automatic credential rotation.

• Multi-Account Access: Easily discover and work with all AWS accounts and roles you have access to through your SSO configuration.

• Full AWS CLI Support: Execute any AWS CLI command directly through your AI assistant with proper authentication and credential management.

• Automated Authentication Flow: Handles browser launch and token polling automatically, making the authentication process simple and intuitive.

Getting Started

Prerequisites

• Node.js (>=18.x): Download
• AWS Account with SSO Configured: You need an AWS account with SSO enabled and appropriate permissions
• AWS CLI v2: For local SSO authentication setup

Step 1: Configure AWS SSO

If you haven't already, set up AWS SSO in your AWS organization:

1. Enable AWS IAM Identity Center (successor to AWS SSO) in your AWS account
2. Configure your identity source (AWS SSO directory, Active Directory, or external IdP)
3. Set up permission sets and assign users to AWS accounts
4. Note your AWS SSO start URL - you'll need this for configuration

Step 2: Configure Credentials

Method A: MCP Config File (Recommended)

Create or edit ~/.mcp/configs.json:

{
	"@aashari/mcp-server-aws-sso": {
		"environments": {
			"DEBUG": "true",
			"AWS_REGION": "us-east-1",
			"AWS_SSO_START_URL": "https://your-sso-portal.awsapps.com/start"
		}
	}
}

• AWS_REGION: Your primary AWS region (e.g., us-east-1)
• AWS_SSO_START_URL: Your AWS SSO portal URL

Method B: Environment Variables

Pass credentials directly when running the server:

DEBUG=true \
AWS_REGION=us-east-1 \
AWS_SSO_START_URL=https://your-sso-portal.awsapps.com/start \
npx -y @aashari/mcp-server-aws-sso

Step 3: Connect Your AI Assistant

Configure your MCP-compatible client to launch this server.

Claude / Cursor Configuration:

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

This configuration launches the server automatically at runtime.

Tools

This section covers the MCP tools available when using this server with an AI assistant. Note that MCP tools use snake_case for tool names and camelCase for parameters.

login

Authenticate with AWS SSO via browser.

{}

or:

{ "launchBrowser": false }

"Login to AWS SSO so I can access my resources."

list_accounts

List all AWS accounts and roles available via SSO.

{}

"Show me all AWS accounts I have access to through SSO."

exec

Execute AWS CLI commands using temporary credentials from AWS SSO.

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

or:

{
	"accountId": "123456789012",
	"roleName": "AdminRole",
	"command": "aws ec2 describe-instances",
	"region": "us-west-2"
}

"List my S3 buckets in account 123456789012 using the ReadOnly role."

Command-Line Interface (CLI)

The CLI uses kebab-case for commands (e.g., login) and options (e.g., --account-id).

Quick Use with npx

# Set required environment variables (replace with your values)
export AWS_SSO_START_URL=https://your-sso-portal.awsapps.com/start
export AWS_REGION=us-east-1

# Login to AWS SSO
npx -y @aashari/mcp-server-aws-sso login

# List available accounts and roles
npx -y @aashari/mcp-server-aws-sso list-accounts

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

Install Globally

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

Then run directly:

mcp-aws-sso login

Discover More CLI Options

Use --help to see flags and usage for all available commands:

mcp-aws-sso --help

Or get detailed help for a specific command:

mcp-aws-sso login --help
mcp-aws-sso exec --help
mcp-aws-sso list-accounts --help

License

ISC License