Transform how you manage and access your AWS infrastructure by connecting Claude, Cursor AI, and other AI assistants directly to your AWS accounts through AWS IAM Identity Center (formerly AWS SSO). Get instant access to your cloud resources, execute commands, and manage EC2 instances using natural language.
Node.js/TypeScript MCP server for AWS Single Sign-On (SSO). Enables AI systems (LLMs) with tools to initiate SSO login (device auth flow), list accounts/roles, and securely execute AWS CLI commands using temporary credentials. Streamlines AI interaction w
2026-11-16
星數
—
工具
—
可用率
—
What You Can Do
✅ Ask AI about your AWS accounts: "Show me all my AWS accounts and available roles"
✅ Execute AWS commands: "List all S3 buckets in my production account"
✅ Manage EC2 instances: "Check the disk usage on server i-123456789"
✅ Access multi-account setups: "Switch to the staging account and describe the VPCs"
✅ Monitor resources: "Get the status of all running EC2 instances"
✅ Run shell commands: "Execute 'df -h' on my web server via SSM"
Perfect For
DevOps Engineers managing multi-account AWS environments and infrastructure automation
Cloud Architects needing quick access to resource information across AWS accounts
Developers who want to check deployments and run AWS CLI commands through AI
SRE Teams monitoring and troubleshooting AWS resources using natural language
IT Administrators managing EC2 instances and executing remote commands securely
Anyone who wants to interact with AWS using conversational AI
Quick Start
Get up and running in 2 minutes:
1. Get Your AWS SSO Setup
Set up AWS IAM Identity Center:
Enable AWS IAM Identity Center in your AWS account
Configure your identity source (AWS directory, Active Directory, or external IdP)
Set up permission sets and assign users to AWS accounts
Note your AWS SSO Start URL (e.g., https://your-company.awsapps.com/start)
2. Try It Instantly
# Set your AWS SSO configuration
export AWS_SSO_START_URL="https://your-company.awsapps.com/start"
export AWS_REGION="us-east-1"
# Start the authentication flow
npx -y @aashari/mcp-server-aws-sso login
# List your accessible accounts and roles
npx -y @aashari/mcp-server-aws-sso ls-accounts
# Execute an AWS command
npx -y @aashari/mcp-server-aws-sso exec-command \
--account-id 123456789012 \
--role-name ReadOnly \
--command "aws s3 ls"
Connect to AI Assistants
For Claude Desktop Users
Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):
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)
# 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)
AWS Configuration:
AWS_SSO_START_URL: Your AWS IAM Identity Center start URL (e.g., https://your-org.awsapps.com/start)
AWS_SSO_REGION or AWS_REGION: AWS region for SSO authentication (e.g., us-east-1)
AWS_PROFILE: AWS profile name (optional, for CLI compatibility)
Available Tools
When integrated with AI assistants via MCP, the following tools are available:
Debug logs are written to: ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log
Each session gets a unique log file. Enable debug logging with DEBUG=true.
Output Format (TOON)
Responses are formatted using TOON (Token-Oriented Object Notation) format, which is optimized for LLM token efficiency. TOON provides a more compact representation than JSON while maintaining readability.
Key Features:
Automatically converts responses to TOON format when available
Falls back to JSON if TOON conversion fails
Truncates large responses (>10KB) with a note about the full response location
Logs full responses to ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log
# ❌ 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*
Large Response Handling
When API responses exceed 10KB, the output is truncated with a message:
[Response truncated for AI consumption. Full response logged to: /path/to/log/file.log]
This ensures AI assistants receive manageable response sizes while developers can access full output in log files.
Technical Details
Architecture
This server follows a clean 5-layer architecture:
CLI Layer (src/cli/): Command-line interface using Commander.js
Tools Layer (src/tools/): MCP tool definitions with Zod validation schemas
Controllers Layer (src/controllers/): Business logic and orchestration
Services Layer (src/services/): External API interactions (AWS SDK)
Debug logs are written to: ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log
Enable debug logging by setting DEBUG=true in your environment.
Caching
SSO tokens: Cached in ~/.aws/sso/cache/ (standard AWS location)
Temporary credentials: Cached for 1 hour per account/role combination
Account information: Fetched fresh on each request (no persistent cache)
Development
# Clone repository
git clone https://github.com/aashari/mcp-server-aws-sso.git
cd mcp-server-aws-sso
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode with HTTP transport
npm run dev:http
# Run with STDIO transport (for MCP client testing)
npm run dev:stdio
# Run with MCP Inspector (visual debugging)
npm run mcp:inspect
# Run tests
npm test
# Run tests with coverage
npm test:coverage
# Lint code
npm run lint
# Format code
npm run format
Available npm Scripts
npm run build - Compile TypeScript to JavaScript
npm run mcp:stdio - Run with STDIO transport
npm run mcp:http - Run with HTTP transport
npm run mcp:inspect - Run with MCP Inspector for debugging
npm test - Run Jest tests
npm run lint - Run ESLint
npm run format - Format code with Prettier
Requirements
Node.js: Version 18.0.0 or higher
AWS CLI: Version 2.x (required only for aws_sso_exec_command)
AWS IAM Identity Center: Configured and accessible
Operating System: macOS, Linux, or Windows
Version History
v3.0.1 (Current)
Fixed picomatch dependency conflict for npm ci
Enhanced raw response logging with truncation for large API responses
Improved AI guidance for AWS SSO login instructions
v3.0.0
BREAKING: Modernized to @modelcontextprotocol/sdk v1.23.0 with registerTool API
Added Node.js version specification (Node 22.14.0 compatibility)
Enhanced logging and error handling
v2.0.0
BREAKING: Fixed AWS CLI execution and credential region mismatch issues
Improved cross-region authentication handling
Prevented dotenv from outputting to STDIO in MCP mode
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
ISC License - See LICENSE file for details
Support
Need help? Here's how to get assistance:
Check the troubleshooting section above - most common issues are covered there
Node.js/TypeScript MCP server for AWS Single Sign-On (SSO). Enables AI systems (LLMs) with tools to initiate SSO login (device auth flow), list accounts/roles, and securely execute AWS CLI commands us
Node.js/TypeScript MCP server for AWS Single Sign-On (SSO). Enables AI systems (LLMs) with tools to initiate SSO login (device auth flow), list accounts/roles, and securely execute AWS CLI commands using temporary credentials. Streamlines AI interaction w
上次檢查時間:2026-11-16。 Node.js/TypeScript MCP server for AWS Single Sign-On (SSO). Enables AI systems (LLMs) with tools to initiate SSO login (device auth flow), list accounts/roles, and securely execute AWS CLI commands using temporary credentials. Streamlines AI interaction w