AWS SSO MCP Server

将AI连接到您的AWS资源

通过AWS IAM身份中心（前身为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实例和执行远程命令
• 任何人 谁想使用会话式人工智能与AWS进行交互

快速开始

2分钟后起床跑步：

1.获取AWS SSO设置

设置AWS IAM身份中心：

1. 启用AWS IAM身份中心 在您的AWS帐户中
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桌面用户

将其添加到您的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助手：

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

🖥️ 管理EC2实例

问你的AI助手：

• *“检查EC2实例i-1234567890abcdef0上的磁盘使用情况”*
• *“通过系统管理器在我的web服务器上运行‘正常运行时间’”*
• *“在生产中的实例i-abc123上执行'systemctl status nginx'”*
• *“从我的所有应用程序服务器获取内存使用情况”*

🔍 基础设施监控

问你的AI助手：

• *“列出我的开发帐户中的所有Lambda函数”*
• *“给我看看us-east-1中的CloudFormation堆栈”*
• *“检查负载平衡器的运行状况”*
• *“获取处于警报状态的最新CloudWatch警报”*

🔄 多账户操作

问你的AI助手：

• *“使用AdminRole切换到帐户987654321098并列出所有安全组”*
• *“比较临时帐户和生产帐户之间的运行实例”*
• *“检查我所有AWS帐户的备份策略”*
• *“审核安全帐户中的IAM用户”*

MCP Tool Examples (Click to expand)

aws_sso_login

基本登录：

{}

自定义登录选项：

{
  "launchBrowser": false
}

aws_sso_status

检查身份验证状态：

{}

aws_sso_ls_accounts

列出所有帐户和角色：

{}

aws_sso_exec_command

列出S3 Buckets：

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

描述特定区域中的EC2实例：

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

检查系统资源：

{
  "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传输（服务器模式的默认值）

• 具有服务器发送事件（SSE）的现代基于HTTP的传输
• 支持多个并发连接
• 更适合基于web的集成和开发
• 默认情况下在端口3000上运行（可通过port env var配置）
• 端点：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 对于服务器模式， stdio 对于MCP客户）
• PORT：HTTP服务器端口（默认值：3000）
• DEBUG：启用调试日志记录（默认值：false）

AWS配置：

• AWS_SSO_START_URL：您的AWS IAM身份中心起始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代理

CLI命令

所有工具也可以作为CLI命令使用 kebab-case.快跑 --help 对于细节（例如。， mcp-aws-sso login --help).

• 登录：通过AWS SSO进行身份验证(--no-launch-browser).前任： mcp-aws-sso login.
• 状态：检查身份验证状态（无选项）。前任： mcp-aws-sso status.
• ls帐户：列出帐户/角色（无选项）。前任： mcp-aws-sso ls-accounts.
• exec命令：运行AWS CLI命令(--account-id, --role-name, --command, --region).前任： mcp-aws-sso exec-command --account-id 123456789012 --role-name ReadOnly --command "aws s3 ls".
• ec2执行命令：在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".

CLI Command Examples (Click to expand)

登录

标准登录（启动浏览器并自动轮询）：

mcp-aws-sso login

不启动浏览器登录：

mcp-aws-sso login --no-launch-browser

执行AWS命令

列出S3 Buckets：

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name ReadOnly \
  --command "aws s3 ls"

列出具有特定区域的EC2实例：

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name AdminRole \
  --region us-west-2 \
  --command "aws ec2 describe-instances --output table"

执行EC2命令

检查系统资源：

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

1. 检查您的AWS SSO配置:

- 验证您的 AWS_SSO_START_URL 正确（应该是您组织的SSO门户） - 确保您的 AWS_REGION 匹配您的SSO区域配置

1. 验证您的SSO设置:

- 确保您可以在浏览器中访问SSO门户 - 检查您的AWS帐户分配是否处于活动状态

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

1. 检查可用帐户和角色:

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

1. 验证帐户ID格式:

- 帐户ID应恰好为12位数字 - 使用来自的确切帐户ID ls-accounts 输出

1. 检查角色权限:

- 确保您有权担任指定的角色 - 使用权限集中的确切角色名称

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

1. 安装AWS CLI v2:

- 下载自 AWS CLI安装指南 - 确保 aws 命令位于系统PATH中

1. 独立测试AWS CLI:

   aws --version
   aws sts get-caller-identity

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

1. 验证EC2实例设置:

- 实例必须安装并运行SSM代理 - 实例需要一个IAM角色 AmazonSSMManagedInstanceCore 政策

1. 检查您的角色权限:

- 您所承担的角色需求 ssm:SendCommand 和 ssm:GetCommandInvocation 权限 - 验证实例是否处于运行状态

1. 测试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桌面集成问题

1. 重新启动克劳德桌面 更新配置文件后
2. 检查状态栏 为“🔗 aws sso”指示器
3. 验证配置文件位置:

- macOS： ~/.claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果你仍然有问题：

1. 运行一个简单的测试命令来验证一切正常
2. 检查 对于类似的问题
3. 使用错误消息和设置详细信息创建新问题

常见问题

我需要什么权限？

对于AWS IAM身份中心（SSO）设置：

• 使用配置的身份源访问AWS IAM身份中心
• AWS管理员分配给您的权限集
• 访问您要管理的特定AWS帐户

对于通过SSM执行的EC2命令：

• 您所承担的角色需求 ssm:SendCommand 和 ssm:GetCommandInvocation 权限
• EC2实例需要一个IAM角色 AmazonSSMManagedInstanceCore 政策
• SSM代理必须在目标实例上安装并运行

我可以在多个AWS组织中使用它吗？

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

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

SSO凭据的有效期是多久？

• SSO令牌：通常为8-12小时（由AWS IAM身份中心管理）
• 临时凭据：每个帐户/角色大约1小时
• 该工具自动处理令牌刷新和凭据缓存
• 令牌过期时，系统将提示您重新进行身份验证

这与哪些AI助手一起工作？

任何支持模型上下文协议（MCP）的AI助手：

• 克劳德桌面版 （最受欢迎且经过充分测试）
• 光标AI （带AI的代码编辑器）
• Continue.dev （VS代码扩展）
• 任何其他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: 不，这直接通过系统管理器使用AWS SDK。

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

此工具直接使用AWS IAM身份中心并管理自己的凭据缓存。它不需要AWS CLI配置文件，但与它们兼容：

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

AWS SSO和AWS IAM身份中心有什么区别？

它们是相同的服务！AWS SSO更名为 AWS IAM身份中心 2022年。此工具可同时使用这两个名称：

• 代码和文档中提及的“AWS SSO”是指AWS IAM身份中心
• 您的起始URL格式保持不变： https://your-org.awsapps.com/start
• 无论命名如何，所有功能都是相同的

TOON格式是什么？

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

• 比JSON更紧凑（在向AI发送数据时节省令牌）
• 仍然可读
• 可用时自动使用，必要时回退到JSON
• 了解更多： @卡通格式/卡通

日志存储在哪里？

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

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

Response Format Examples (Click to expand)

输出格式（TOON）

响应的格式使用 TOON（面向令牌的对象表示法） 该格式针对LLM令牌效率进行了优化。TOON提供了比JSON更紧凑的表示，同时保持了可读性。

主要特点：

• 可用时自动将响应转换为TOON格式
• 如果TOON转换失败，则返回JSON
• 截断大响应（>10KB），并注明完整响应位置
• 记录对的完整响应 ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log

MCP工具响应示例(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*

错误响应示例

# ❌ 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. Utils图层 (src/utils/)：共享实用程序（日志记录、配置、缓存、格式化）

关键依赖关系

• @模型上下文协议/sdk v1.23.0:MCP协议实现
• @awssdk/客户端单点登录 v3.893.0:AWS SSO API客户端
• @aws-sdk/客户端ssm v3.893.0:用于EC2命令的AWS系统管理器
• @卡通格式/卡通 v2.0.1：令牌高效输出格式
• 黄道带 v4.1.13：运行时类型验证
• 指挥官 v14.0.2：命令行界面框架

日志记录

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

通过设置启用调试日志记录 DEBUG=true 在您的环境中。

缓存

• SSO令牌：缓存在 ~/.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检查器进行调试
• 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身份中心：已配置且可访问
• 操作系统：macOS、Linux或Windows

版本历史记录

v3.0.1（当前）

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

v3.0.0

• 突发：使用registerTool API将其现代化为@modelcontextprotocol/sdk v1.23.0
• 添加了Node.js版本规范（与Node 22.14.0兼容）
• 增强的日志记录和错误处理

v2.0.0版本

• 突发：修复了AWS CLI执行和凭据区域不匹配问题
• 改进了跨区域身份验证处理
• 防止dotenv在MCP模式下输出到STDIO

看 更改日志.md 查看完整的版本历史记录。

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

许可证

ISC许可证-有关详细信息，请参阅许可证文件

支持

需要帮助？以下是如何获得帮助：

1. 检查上面的故障排除部分 -其中涵盖了最常见的问题
2. 访问我们的GitHub仓库 有关文档和示例：
3. 报告问题 在
4. 开始讨论 用于功能请求或一般问题
5. 检查调试日志 在 ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log 有关详细的错误信息

______________________________________________________________________

内置： TypeScript、MCP SDK、适用于JavaScript v3的AWS SDK、TOON格式

*为希望将人工智能引入AWS工作流程的DevOps团队精心打造。*