AWS SSO MCP Server

How to use

Use an MCP-compatible AI assistant to authenticate with AWS SSO and issue commands through the MCP server. You can ask to list accounts and roles, run AWS CLI commands, describe EC2/VPC/RDS resources, switch between accounts, monitor running resources, and execute shell commands on EC2 instances via Systems Manager. Start by logging in, listing available accounts, then choosing an account/role to run a command.

How to install

Prerequisites: Node.js v18+ and an AWS IAM Identity Center setup in your organization.

Step 1: Install the MCP server package globally so your AI assistant can connect to it.

Step 2: Configure access to AWS SSO by providing your Start URL and region when prompted or via environment variables.

Step 3: Start the MCP server in STDIO mode for local MCP clients, or run in HTTP mode for server-based integrations.

Step 4: Point your MCP client to the server transport and begin issuing commands.

HTTP transport (server mode) configuration

{
  "aws-sso": {
    "type": "http",
    "name": "aws_sso_server",
    "url": "http://localhost:3000/mcp",
    "args": []
  }
}

STDIO transport (client mode) configuration

{
  "aws-sso": {
    "type": "stdio",
    "name": "aws_sso_client",
    "command": "npx",
    "args": ["-y", "@aashari/mcp-server-aws-sso"],
    "env": {
      "AWS_SSO_START_URL": "https://your-company.awsapps.com/start",
      "AWS_REGION": "us-east-1"
    }
  }
}

Environment variables

The MCP server uses environment variables to configure AWS SSO access. Common keys include AWS_SSO_START_URL for the start URL, AWS_SSO_REGION or AWS_REGION for the AWS region, and AWS_PROFILE for CLI compatibility. Enable debug logging with DEBUG=true if you need detailed output.

Real-world usage patterns

• Authenticate with AWS SSO to obtain short-lived credentials for your accounts and roles.
• List all accessible accounts and their roles to discover permissions.
• Execute AWS CLI commands in a chosen account/role, for example listing S3 buckets or describing EC2 instances.
• Describe VPCs, RDS databases, or other resources across multiple accounts.
• Switch context between accounts to run cross-account commands or audits.
• Run shell commands on EC2 instances via Systems Manager without requiring SSH access.

Security considerations

All credentials are temporary and cached with automatic refresh. The tool runs locally on your machine and does not send your data to third-party servers unless you explicitly interact with network-enabled MCP transports. Ensure your AWS permissions align with the actions you perform and monitor token lifetimes.

Troubleshooting

If authentication fails, re-authenticate with AWS SSO, verify the Start URL and region, and confirm your account and role permissions are active. If AWS CLI commands fail due to missing CLI, install AWS CLI v2 and verify the aws command is accessible. For EC2/SSM issues, ensure the target instance has the SSM Agent installed and the proper IAM role.

Notes

The MCP server supports both HTTP and STDIO transport modes. Use HTTP for server-based integrations and STDIO for local MCP clients. Environment variables and example commands shown here guide you through typical setups.

aws_sso_login

Initiates the AWS SSO device authorization flow, caches tokens, and handles re-authentication when needed.

aws_sso_status

Checks current authentication status and token expiration.

aws_sso_ls_accounts

Lists all accessible AWS accounts and the roles you can assume.

aws_sso_exec_command

Executes an AWS CLI command using SSO credentials for a specified account/role, with optional region.

aws_sso_ec2_exec_command

Executes a shell command on an EC2 instance via AWS Systems Manager (SSM) without SSH.