AWS SSO MCP Server

将 AI 接入您的 AWS 资源

通过 AWS IAM Identity Center（前身为 AWS SSO），将 Claude、Cursor AI 和其他 AI 助手直接连接到您的 AWS 账户，彻底改变您管理和访问 AWS 基础设施的方式。即时访问云资源、执行命令，并使用自然语言管理 EC2 实例。

您可以做什么

✅ 向 AI 询问您的 AWS 账户：“显示我的所有 AWS 账户和可用角色”
✅ 执行 AWS 命令：“列出我的生产账户中的所有 S3 存储桶”
✅ 管理 EC2 实例：“检查服务器 i-123456789 的磁盘使用情况”
✅ 访问多账户环境：“切换到预发布账户并描述 VPC”
✅ 监控资源：“获取所有正在运行的 EC2 实例的状态”
✅ 运行 Shell 命令：“通过 SSM 在我的 Web 服务器上执行 ‘df -h’”

适用人群

• DevOps 工程师：管理多账户 AWS 环境并自动化基础设施
• 云架构师：需要快速访问多个 AWS 账户中的资源信息
• 开发者：希望通过 AI 检查部署并运行 AWS CLI 命令
• SRE 团队：使用自然语言监控和排查 AWS 资源问题
• IT 管理员：管理 EC2 实例并安全地执行远程命令
• 任何人：希望使用对话式 AI 与 AWS 交互

快速开始

只需 2 分钟即可开始使用：

1. 配置 AWS SSO

设置 AWS IAM Identity Center：

1. 在您的 AWS 账户中启用 AWS IAM Identity Center
2. 配置您的身份源（AWS 目录、Active Directory 或外部 IdP）
3. 设置权限集并将用户分配到 AWS 账户
4. 记下您的 AWS SSO 起始 URL（例如，https://your-company.awsapps.com/start）

2. 立即试用

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

连接到 AI 助手

Claude Desktop 用户

将以下内容添加到您的 Claude 配置文件（~/.claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "aws-sso": {
      "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"
      }
    }
  }
}

重启 Claude Desktop，您将在状态栏中看到“🔗 aws-sso”。

其他 AI 助手

大多数 AI 助手都支持 MCP。全局安装该服务：

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

然后配置您的 AI 助手，以 STDIO 传输方式使用该 MCP 服务。

备选方案：配置文件

创建 ~/.mcp/configs.json，进行系统范围的配置：

{
  "aws-sso": {
    "environments": {
      "AWS_SSO_START_URL": "https://your-company.awsapps.com/start",
      "AWS_REGION": "us-east-1",
      "DEBUG": "false"
    }
  }
}

**备选配置键：**系统还接受 "@aashari/mcp-server-aws-sso" 或 "mcp-server-aws-sso"，可替代 "aws-sso"。

实际示例

🔐 身份验证与探索

向您的 AI 助手提问：

• “登录 AWS SSO 并显示我的身份验证状态”
• “列出我的所有 AWS 账户以及我可以承担的角色”
• “检查我是否仍通过 AWS 身份验证”
• “显示我有权访问哪些 AWS 账户”

🛠️ 执行 AWS 命令

向您的 AI 助手提问：

• “使用 ReadOnly 角色列出我的生产账户中的所有 S3 存储桶”
• “显示 us-west-2 区域中所有正在运行的 EC2 实例”
• “描述我的预发布 AWS 账户中的 VPC”
• “获取账户 123456789012 中我的 RDS 数据库的状态”

🖥️ 管理 EC2 实例

向您的 AI 助手提问：

• “检查 EC2 实例 i-1234567890abcdef0 的磁盘使用情况”
• “通过 Systems Manager 在我的 Web 服务器上运行 ‘uptime’”
• “在生产环境中的实例 i-abc123 上执行 ‘systemctl status nginx’”
• “获取我所有应用服务器的内存使用情况”

🔍 基础设施监控

向您的 AI 助手提问：

• “列出我的开发账户中的所有 Lambda 函数”
• “显示 us-east-1 中的 CloudFormation 堆栈”
• “检查我的负载均衡器的运行状况”
• “获取状态为 ALARM 的最新 CloudWatch 警报”

🔄 多账号操作

向 AI 助手提问：

• “切换到账号 987654321098，使用 AdminRole，并列出所有安全组”
• “比较暂存和生产账号中的运行中实例”
• “检查我所有 AWS 账号的备份策略”
• “审计安全账号中的 IAM 用户”

{}

{
  "launchBrowser": false
}

{}

{}

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

传输模式

此服务支持两种传输模式，适用于不同的集成场景：

STDIO 传输（MCP 客户端的默认模式）

• 通过 stdin/stdout 进行传统的子进程通信
• 适用于本地 AI 助手集成（Claude Desktop、Cursor AI）
• 使用基于管道的通信直接交换 MCP 协议消息

# 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 传输（服务模式的默认模式）

• 基于现代 HTTP 的传输方式，使用服务器发送事件（SSE）
• 支持多个并发连接
• 更适合基于 Web 的集成和开发
• 默认运行于 3000 端口（可通过 PORT 环境变量配置）
• 端点：http://localhost:3000/mcp
• 健康检查：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

环境变量

传输配置：

• TRANSPORT_MODE：设置为 stdio 或 http（默认值：服务模式下为 http，MCP 客户端下为 stdio）
• PORT：HTTP 服务端口（默认值：3000）
• DEBUG：启用调试日志（默认值：false）

AWS 配置：

• AWS_SSO_START_URL：AWS IAM Identity Center 启动 URL（例如：https://your-org.awsapps.com/start）
• AWS_SSO_REGION 或 AWS_REGION：用于 SSO 身份验证的 AWS 区域（例如：us-east-1）
• AWS_PROFILE：AWS 配置文件名称（可选，用于兼容 CLI）

可用工具

通过 MCP 与 AI 助手集成后，可使用以下工具：

身份验证工具

• aws_sso_login：启动 AWS SSO 设备授权流程

  • 参数：launchBrowser（可选，布尔值，默认值：true）
  • 自动打开浏览器进行身份验证
  • 处理设备授权码流程
  • 缓存令牌以供后续操作使用

• aws_sso_status：检查当前身份验证状态

  • 无需参数
  • 返回会话详情和过期时间
  • 验证缓存令牌的有效性

账号管理工具

• aws_sso_ls_accounts：列出所有可访问的 AWS 账号和角色
  • 无需参数
  • 显示账号 ID、名称、邮箱和可用角色
  • 对于了解可使用的账号和角色至关重要

命令执行工具

• aws_sso_exec_command：使用 SSO 凭证执行 AWS CLI 命令

  • 必填参数：accountId、roleName、command
  • 可选参数：region
  • 自动获取并缓存临时凭证
  • 支持任何 AWS CLI 命令

• aws_sso_ec2_exec_command：通过 SSM 在 EC2 实例上执行 Shell 命令

  • 必填参数：instanceId、accountId、roleName、command
  • 可选参数：region
  • 无需 SSH 访问（使用 AWS Systems Manager）
  • 实例必须安装 SSM Agent

CLI 命令

所有工具也都可通过 kebab-case 格式的 CLI 命令使用。运行 --help 查看详情（例如，mcp-aws-sso login --help）。

• login：通过 AWS SSO 进行身份验证（--no-launch-browser）。例如：mcp-aws-sso login。
• status：检查身份验证状态（无选项）。例如：mcp-aws-sso status。
• ls-accounts：列出账户/角色（无选项）。例如：mcp-aws-sso ls-accounts。
• exec-command：运行 AWS CLI 命令（--account-id、--role-name、--command、--region）。例如：mcp-aws-sso exec-command --account-id 123456789012 --role-name ReadOnly --command "aws s3 ls"。
• ec2-exec-command：在 EC2 上运行 Shell 命令（--instance-id、--account-id、--role-name、--command、--region）。例如：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"

故障排除

“身份验证失败”或“令牌已过期”

1. 使用 AWS SSO 重新进行身份验证：

   # Test your SSO configuration
   npx -y @aashari/mcp-server-aws-sso login
   

2. 检查 AWS SSO 配置：

   • 确认 AWS_SSO_START_URL 正确（应为组织的 SSO 门户）
   • 确保 AWS_REGION 与 SSO 区域配置一致

3. 验证 SSO 设置：

   • 确保可以在浏览器中访问 SSO 门户
   • 检查分配给你的 AWS 账户是否已启用

“未找到账户”或“未找到角色”

1. 检查可用账户和角色：

   # List all accessible accounts
   npx -y @aashari/mcp-server-aws-sso ls-accounts
   

2. 验证账户 ID 格式：

   • 账户 ID 必须恰好为 12 位数字
   • 使用 ls-accounts 输出中的确切账户 ID

3. 检查角色权限：

   • 确保你有权代入指定角色
   • 使用权限集中的确切角色名称

“未找到 AWS CLI”或命令执行错误

1. 安装 AWS CLI v2：

   • 从 AWS CLI 安装指南 下载
   • 确保系统 PATH 中包含 aws 命令

2. 独立测试 AWS CLI：

   aws --version
   aws sts get-caller-identity
   

“EC2 命令失败”或“SSM 连接问题”

1. 验证 EC2 实例设置：

   • 实例必须安装并运行 SSM Agent
   • 实例需要具有 AmazonSSMManagedInstanceCore 策略的 IAM 角色

2. 检查角色权限：

   • 代入的角色需要 ssm:SendCommand 和 ssm:GetCommandInvocation 权限
   • 确认实例处于运行状态

3. 测试 SSM 连通性：

   # Test if instance is reachable via SSM
   npx -y @aashari/mcp-server-aws-sso exec-command \
     --account-id YOUR_ACCOUNT \
     --role-name YOUR_ROLE \
     --command "aws ssm describe-instance-information"
   

Claude Desktop 集成问题

1. 更新配置文件后，重启 Claude Desktop
2. 检查状态栏中的“🔗 aws-sso”指示器
3. 验证配置文件位置：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果问题仍未解决：

1. 运行简单的测试命令，确认一切正常
2. 在 GitHub Issues 中查找类似问题
3. 创建新 Issue，并提供错误消息和设置详情

常见问题

我需要哪些权限？

AWS IAM Identity Center（SSO）设置所需权限：

• 有权访问已配置身份源的 AWS IAM Identity Center
• AWS 管理员分配给你的权限集
• 有权访问你要管理的特定 AWS 账户

通过 SSM 执行 EC2 命令所需权限：

• 代入的角色需要 ssm:SendCommand 和 ssm:GetCommandInvocation 权限
• EC2 实例需要具有 AmazonSSMManagedInstanceCore 策略的 IAM 角色
• 目标实例必须安装并运行 SSM Agent

我可以将其用于多个 AWS 组织吗？

目前，每次安装一次仅支持一个 AWS SSO 启动 URL。对于多个组织，你可以：

• 在不同会话之间切换 AWS_SSO_START_URL 环境变量
• 使用不同配置运行多个实例
• 为不同组织使用多个 Claude Desktop 配置

SSO 凭证的有效期是多久？

• SSO 令牌：通常为 8-12 小时（由 AWS IAM Identity Center 管理）
• 临时凭证：每个账户／角色约 1 小时
• 该工具会自动处理令牌刷新和凭证缓存
• 令牌过期时，系统会提示你重新进行身份验证

该工具支持哪些 AI 助手？

任何支持 Model Context Protocol（MCP）的 AI 助手：

• Claude Desktop（最受欢迎且经过充分测试）
• Cursor AI（带 AI 的代码编辑器）
• Continue.dev（VS Code 扩展）
• 任何其他兼容 MCP 的客户端

我的数据安全吗？

是的！该工具将安全放在首位：

• 完全在本地计算机上运行（不使用外部服务器）
• 使用你自己的 AWS SSO 凭证（不使用第三方身份验证）
• 绝不会向第三方发送你的数据
• 只访问你明确授权的内容
• 使用会自动过期的 AWS 临时凭证
• 遵循 AWS 凭证管理最佳实践
• 凭证存储在标准 AWS 位置（~/.aws/）

我需要安装 AWS CLI 吗？

**对于 aws_sso_exec_command：**需要，执行 AWS 命令需要 AWS CLI v2。

**对于其他工具：**不需要，身份验证（aws_sso_login）、状态检查（aws_sso_status）和账户列表（aws_sso_ls_accounts）均可在未安装 AWS CLI 的情况下使用。

**对于 aws_sso_ec2_exec_command：**不需要，该工具通过 Systems Manager 直接使用 AWS SDK。

我可以将其与 AWS CLI 配置文件搭配使用吗？

该工具直接使用 AWS IAM Identity Center，并管理自己的凭证缓存。它不需要 AWS CLI 配置文件，但与之兼容：

• 该工具将凭证存储在 ~/.aws/sso/cache/（AWS 标准位置）
• 你可以选择设置 AWS_PROFILE，以便与其他 AWS 工具兼容
• 该工具独立于 AWS CLI 配置文件设置运行

AWS SSO 和 AWS IAM Identity Center 有什么区别？

它们是同一项服务！AWS SSO 于 2022 年更名为 AWS IAM Identity Center。该工具兼容这两种名称：

• 代码和文档中提到的 “AWS SSO” 均指 AWS IAM Identity Center
• 启动 URL 格式保持不变：https://your-org.awsapps.com/start
• 无论名称如何变化，所有功能都完全相同

什么是 TOON 格式？

TOON（Token-Oriented Object Notation，面向令牌的对象表示法）是一种针对大语言模型优化的输出格式：

• 比 JSON 更紧凑（向 AI 发送数据时可节省令牌）
• 仍然易于阅读
• 有可用版本时会自动使用；如有需要则回退到 JSON
• 了解更多： @toon-format/toon

日志存储在哪里？

调试日志写入：~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log

每个会话都会生成唯一的日志文件。使用 DEBUG=true 启用调试日志记录。

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

当 API 响应超过 10KB 时，输出会被截断，并显示以下消息：

[Response truncated for AI consumption. Full response logged to: /path/to/log/file.log]

这样可确保 AI 助手收到便于处理的响应大小，同时开发者可以在日志文件中查看完整输出。

技术详情

架构

此服务采用清晰的 5 层架构：

1. CLI 层（src/cli/）：使用 Commander.js 的命令行界面
2. 工具层（src/tools/）：使用 Zod 验证架构定义 MCP 工具
3. 控制器层（src/controllers/）：业务逻辑与编排
4. 服务层（src/services/）：外部 API 交互（AWS SDK）
5. 工具函数层（src/utils/）：共享工具函数（日志记录、配置、缓存、格式化）

主要依赖项

• @modelcontextprotocol/sdk v1.23.0：MCP 协议实现
• @aws-sdk/client-sso v3.893.0：AWS SSO API 客户端
• @aws-sdk/client-ssm v3.893.0：用于 EC2 命令的 AWS Systems Manager
• @toon-format/toon v2.0.1：节省 Token 的输出格式
• zod v4.1.13：运行时类型验证
• commander v14.0.2：CLI 框架

日志记录

调试日志写入位置：~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log

在环境中设置 DEBUG=true 即可启用调试日志记录。

缓存

• SSO Token：缓存在 ~/.aws/sso/cache/（AWS 标准位置）
• 临时凭证：按账户和角色组合缓存 1 小时
• 账户信息：每次请求时重新获取（不使用持久缓存）

开发

# 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

可用的 npm 脚本

• npm run build - 将 TypeScript 编译为 JavaScript
• npm run mcp:stdio - 使用 STDIO 传输运行
• npm run mcp:http - 使用 HTTP 传输运行
• npm run mcp:inspect - 使用 MCP Inspector 运行以进行调试
• npm test - 运行 Jest 测试
• npm run lint - 运行 ESLint
• npm run format - 使用 Prettier 格式化代码

要求

• Node.js：版本 18.0.0 或更高
• AWS CLI：版本 2.x（仅 aws_sso_exec_command 需要）
• AWS IAM Identity Center：已配置且可访问
• 操作系统：macOS、Linux 或 Windows

版本历史

v3.0.1（当前）

• 修复 npm ci 的 picomatch 依赖冲突
• 增强原始响应日志记录，并对大型 API 响应进行截断
• 改进 AWS SSO 登录说明的 AI 指引

v3.0.0

• 重大变更：升级至 @modelcontextprotocol/sdk v1.23.0，并采用 registerTool API
• 添加 Node.js 版本要求（兼容 Node 22.14.0）
• 增强日志记录与错误处理

v2.0.0

• 重大变更：修复 AWS CLI 执行和凭证区域不匹配问题
• 改进跨区域身份验证处理
• 防止 dotenv 在 MCP 模式下向 STDIO 输出内容

完整版本历史请参阅 CHANGELOG.md。

贡献

欢迎贡献！请随时提交 Pull Request。对于重大变更，请先提交 issue，讨论您希望进行的更改。

许可证

ISC License - 详情请参阅 LICENSE 文件

支持

需要帮助？以下是获取支持的方式：

1. 查看上方的故障排除部分 - 大多数常见问题都已涵盖
2. 访问我们的 GitHub 仓库获取文档和示例：github.com/aashari/mcp-server-aws-sso
3. 在 GitHub Issues 报告问题
4. 发起讨论，提出功能请求或一般性问题
5. 查看调试日志，获取详细错误信息：~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log

构建技术： TypeScript、MCP SDK、AWS SDK for JavaScript v3、TOON Format

用心打造，献给希望将 AI 引入 AWS 工作流的 DevOps 团队。