Yaw Labs AWS MCP

@yawlabs/aws-mcp

单击即可将其添加到本地 Yaw MCP 配置中，使其在每个 Yaw Terminal 会话中都可用。也可以在下方手动安装。

这是一款供 AI 助手使用的精简 AWS MCP：一个服务、一条配置项、内置 SSO 重新认证、对 1,300 多种资源类型提供通用 CRUD、实时文档查询，以及用于批量工作流的服务端脚本。

它是 AWS 官方 MCP 服务的替代方案，而非补充——两者都能调用任意 AWS API，因此同时运行会让模型获得两种重叠的方式来完成相同任务。（AWS 对自己的旧版服务也给出了相同建议：其设置指南建议移除它们，“以避免可能混淆 AI Agent 的工具冲突”。）二选一即可。两者覆盖范围重叠，但形式不同。客观比较如下：

• AWS MCP Server —— AWS 托管的服务，自 2026 年 5 月起正式发布，属于 Agent Toolkit for AWS。其优势包括由 AWS 团队精选的技能、服务端 Python 沙箱（run_script），具备最新的 API 覆盖范围、只读无服务器故障排查能力（Lambda diagnose、近期变更、X-Ray 跟踪摘要）、用于区分其调用与直接 API 调用的 IAM 条件键，以及按工具划分的 CloudWatch 指标。截至 2026 年 9 月，run_script 是它调用 AWS API 的唯一通用方式——单次调用工具 call_aws 已被移除——因此每次调用，即使只是单次 describe，模型都要编写 Python 脚本。端点运行在 us-east-1 和 eu-central-1。有两种连接方式：
  • OAuth，通过 AWS Sign-in（自 2026 年 7 月起）：无需安装任何内容——客户端会打开浏览器并直接连接到端点。每个会话绑定一个 IAM 角色，刷新有效期最长为 12 小时；主体需要拥有 signin:AuthorizeOAuth2Access 和 signin:CreateOAuth2Token 权限。
  • SigV4，通过使用 uv 运行的本地代理（AWS 指南中的命令为 uvx mcp-proxy-for-aws-cli@latest），并使用 AWS CLI 凭证签名（CLI 2.32.0+）。AWS 建议终端和 IDE 编码 Agent 使用此方式；这也是唯一支持在每次调用时切换配置文件的方式，且可切换的配置文件由代理启动时固定的允许列表决定。从 AWS CLI 2.35.0 起，aws configure agent-toolkit 会自动将 SigV4 配置项（uvx mcp-proxy-for-aws@latest）写入 Agent 的 MCP 配置，键名为 aws-mcp。
• @yawlabs/aws-mcp（本服务）——通过 npm 安装，在本地使用你自己的 aws CLI 和配置文件运行：只需一行 npx 命令，无需 uv、代理或托管中转。它在 SSO 重新登录方面更具优势，尤其适用于 aws sso login 的浏览器跳转失败时（Windows 上尤为常见）；每次工具调用执行一个 AWS 操作（aws_call 接受 service、operation 和 params，因此主机的审批提示会显示操作本身，而不是脚本）；还提供便捷的 CCAPI CRUD 和试运行差异、多区域和多账户扇出、IAM 权限预检查，以及在需要批处理时使用的 JS 脚本工具（在进程内运行，并非安全沙箱——详见工具表）。它还内置 AWS 实时文档搜索和页面读取，因此无论选择哪种方案，都不需要另装文档服务——其覆盖内容与官方服务的 search_documentation / read_documentation 相同，但不包含其主题路由或技能结果。 真正能与任一选择搭配使用的 MCP，是 awslabs/mcp 中按服务划分的 MCP 服务，它们能实现通用 AWS API 工具无法做到的功能——Bedrock 的 Agentic 知识库检索就是最典型的例子（参见配套配置）。AWS 现在称该仓库已由 Agent Toolkit for AWS 接替；它仍可使用，也接受贡献，但其中一些 MCP 服务已弃用或被取代——包括其通用 AWS API 服务，因此添加前请先查看相应 MCP 服务的 README。

该服务力求妥善处理五件事：

1. SSO 重新登录。 当会话中的令牌过期时，aws sso login 会尝试从子进程打开浏览器——在 Windows 上（有时也会在其他环境中），这类跳转会悄无声息地失败。你只能切换到终端，自己运行命令，然后再切回来。--no-browser 设备代码流程解决了这个问题：助手会显示一个简短 URL 和代码，点击一次即可完成。（单独使用 --no-browser 已经不够了——AWS CLI 2.22.0 将 PKCE 授权码流程设为默认流程，而且不会打印短代码——因此此服务会将其与 --use-device-code 配合使用，并探测一次 aws --version，以兼容 2.22 之前的 CLI。）此外，aws_refresh_if_expiring_soon 还可以在较长的工作流开始前主动续期。AWS 的托管服务绕开了这个问题，而不是解决它。在其 OAuth 流程中，MCP 客户端会运行自己的浏览器登录，令牌会绑定到该客户端和该服务，因此机器上的其他程序无法受益；在其 SigV4 流程中，AWS 的故障排查表会让 SSO 用户自行运行 aws sso login，然后重启 MCP 客户端。在这里，重新登录会刷新同一个 ~/.aws/sso/cache 令牌，CLI、SDK 和机器上的所有其他工具读取的都是它。
2. 调用任意 AWS API。 aws_call 直接代理 aws CLI。一个工具就能覆盖完整的 API 面——包括 AWS 明天新增的服务——无需打包 SDK，也不会造成每个服务都要单独配一组工具的泛滥。这并非空谈：2026 年 9 月新增的功能——AWS Batch 批量 cancel-jobs / terminate-jobs（CLI 2.36.44）、STS 会话令牌大小字段（2.36.45）、Elastic Beanstalk 集群环境（2.36.47）、“Tunnel” VPC 终端节点（2.36.48）——只要本地 aws CLI 支持，就能立即使用，无需升级 @yawlabs/aws-mcp。如果 CLI 太旧，不支持某项操作，就会在发送任何内容之前拒绝该操作，并提示升级。aws_paginate 处理分页的列表／描述操作，aws_multi_region 并行地将同一操作分发到 N 个区域，JMESPath query 参数则可在服务端精简响应。应尽早使用这些工具，不要等到此服务的 5 MB 输出上限：MCP 宿主很快就会先行截断——Claude Code 会在 10,000 个令牌时发出警告，并且默认会将任何超过 25,000 个令牌的结果保存到文件中，供模型读回。
3. 跨服务的通用 CRUD。 aws_resource_*（七个工具，包括用于预览试运行结果的 aws_resource_diff）封装了 AWS Cloud Control API，因此，对于任何具有 CloudFormation 架构的控制平面资源，都可以使用同一生命周期——获取／列出／创建／更新／删除／查看状态：Lambda 函数、S3 存储桶、IAM 角色、SSM 参数、RDS 实例，以及 AWS 发布列表中的其余 1,300 种类型（并非每种类型都支持每种操作）。传入 awaitCompletion: true，服务就会为你轮询异步创建／更新／删除操作，直到进入终止状态。AWS Labs 于 2026 年 3 月弃用了自己的 Cloud Control API MCP 服务，迁移指南也没有列出资源获取／列出／创建／更新／删除操作的直接替代方案：后继方案改为编写 CloudFormation 和 CDK。在数据平面上，DynamoDB get-item / query 和 Bedrock converse 都是 aws_call 可以处理的普通操作（DynamoDB 的值仍保留在其类型化 JSON 中，如 {"S": "..."}），Lambda 调用则有专用工具 aws_lambda_invoke。有三类操作无法通过 aws_call 执行：将响应正文写入位置参数指定的输出文件的操作（S3 get-object、Bedrock invoke-model）；CLI 手写的命令，这些命令未注册 --cli-input-json（s3 cp/ls/sync、logs tail、cloudformation deploy）；以及 CLI 完全未提供的事件流操作（Bedrock converse-stream、invoke-agent、Agent 知识库检索）。
4. 实时 AWS 文档。 aws_docs_search 会查询与 docs.aws.amazon.com 搜索框相同的后端；aws_docs_read 会获取文档页面并以分页 Markdown 格式返回。无需安装第二个 MCP 服务，Agent 就能发现新服务并查找准确的参数名称。
5. 一次往返处理批量工作流。 aws_script 会在 node:vm 上下文中运行一段简短的 JS 代码片段，并提供 aws.call、aws.paginate、aws.paginateAll、aws.resource.*、aws.logsTail、aws.metricsQuery、aws.iamSimulate、aws.multiRegion、aws.assumeRole 和 aws.docs.{search,read}。最适合“列出 X、为每项获取 Y、返回 Z”这类原本需要调用 N 次工具的流水线。它与 AWS 的 run_script（Python，在服务端沙箱中运行）思路相同；run_script 目前是该服务调用 AWS API 的唯一通用方式。这里的 aws_script 则是批处理选项——使用原生 JS，在本地运行——单项操作则使用 aws_call。

可选配套：AWS Labs 按服务划分的服务

对于通用 AWS API 工具无法完成的工作，可在此工具之外添加相关的 awslabs/mcp 服务。Bedrock 的 Agentic 知识库检索是最典型的情况：它会调用 AgenticRetrieveStream，这是 AWS CLI 命令表中未列出的事件流操作，因此任何基于 CLI 的工具——包括 aws_call——都无法访问它。（普通检索 bedrock-agent-runtime retrieve 是常规的 aws_call 操作。）这些是通过 uvx 运行的 Python 服务，并且工具名称与此工具没有重叠，因此可以轻松搭配使用：

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "@yawlabs/aws-mcp@latest"]
    },
    "aws-bedrock-kb": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": { "AWS_PROFILE": "my-profile", "AWS_REGION": "us-east-1" }
    }
  }
}

其 Agentic 工具适用于托管知识库，并且默认情况下，服务只会列出带有 mcp-multirag-kb=true 标签的知识库；其 README 介绍了标签和 IAM 权限。请勿使用旧版 awslabs.lambda-mcp-server：它的每个版本都已从 PyPI 撤回，而且这里已内置 Lambda 调用工具 aws_lambda_invoke。

何时选择此工具，而不是其他 AWS MCP

需求	最佳选择
仅通过 Node/npm 安装，在本地使用自己的 aws CLI 和配置文件运行（无需 uv、无需代理）	@yawlabs/aws-mcp
本地不安装任何内容（远程服务，通过浏览器登录）	AWS MCP Server（OAuth）
在 Windows 上重新登录 SSO 时遇到问题 / 浏览器交接故障，并为机器上的所有工具统一修复	@yawlabs/aws-mcp（aws_login_start 设备码流程）
每次工具调用执行一个 AWS 操作——审批提示会显示 service、operation 和 params，而不是脚本	@yawlabs/aws-mcp（aws_call）
跨 1,300 多种资源类型执行通用 CRUD 操作	@yawlabs/aws-mcp（aws_resource_*）
应用更新前先试运行	@yawlabs/aws-mcp（aws_resource_diff）
一次调用分发到多个区域	@yawlabs/aws-mcp（aws_multi_region）
一次调用对多个账户执行相同操作	@yawlabs/aws-mcp（aws_multi_account）
将 N 次工具调用批量合并为一次往返（JS）	@yawlabs/aws-mcp（aws_script）
尝试操作前检查 IAM 权限	@yawlabs/aws-mcp（aws_iam_simulate）
在一个会话中跨账户 / 跨角色操作	任一方案——此服务每次调用都可以指定任意已配置的 profile，并通过 aws_assume_role 支持 STS 角色链；AWS 的服务每次调用只支持一个配置文件，且仅使用 SigV4，该配置文件必须在其代理启动时声明（OAuth 会话仅对应一个角色）
在服务端执行沙盒化 Python 脚本	AWS MCP Server（run_script）
通过托管端点获取数日前仍为最新的 API 覆盖	AWS MCP Server（run_script）
由 AWS 团队精选的最佳实践技能	AWS MCP Server（retrieve_skill）
引导式 Lambda 故障排查（诊断、近期更改、跟踪摘要）	AWS MCP Server（无服务器能力）
为基于 CLI 的工具无法访问的功能提供按服务划分的类型化辅助工具（Bedrock Agentic 知识库检索，……）	awslabs/mcp（按服务划分的服务）

@yawlabs/aws-mcp 和 AWS 官方服务是二选一的方案——请选择最符合你需求的方案。awslabs/mcp 的按服务划分的服务可以与任一方案轻松搭配使用。

此服务借鉴了 AWS 官方服务的哪些功能

功劳应归于应得之人——这里有两项功能是根据 AWS 官方 MCP 服务设计的：

• aws_script 与官方服务的 run_script 类似：这是一种脚本工具，可将“列出 X、逐个获取 Y、返回 Z”的流程合并为一次往返调用。官方服务使用 Python，在服务端进行沙箱隔离，如今这是该服务唯一的通用 API 调用方式；本服务则原生使用 JS，在本服务自己的进程中运行——请参阅工具表中的信任说明——并与 aws_call 并存，而非取而代之。
• aws_docs_search / aws_docs_read 的加入，让你无论选择哪个服务，都不必另行使用文档 MCP。它们涵盖的内容与官方服务的 search_documentation / read_documentation 相同——实时搜索和页面读取——但不包含其主题路由或技能结果。

其余功能——SSO 设备代码重新登录、支持试运行差异对比的 CCAPI CRUD、多区域扇出、IAM 前置检查——均为本服务独有。

工具

工具	功能
aws_whoami	当前身份（账户、ARN）以及 SSO 令牌过期倒计时。请先调用此工具。
aws_login_start	启动 aws sso login --no-browser --use-device-code，返回验证 URL、短代码和 sessionId。（对于早于 2.22.0 的 AWS CLI，会省略 --use-device-code，因为设备授权模式已是默认设置。）
aws_login_complete	阻塞等待 SSO 子进程完成（你需要在浏览器中进行身份验证），然后返回新身份。
aws_refresh_if_expiring_soon	检查缓存的 SSO 令牌，并在剩余时间少于 thresholdMinutes 时（默认值为 10）自动启动刷新。一次往返即可完成“我的令牌是否即将过期？如果是，就重新登录。”
aws_session_set	为本次 MCP 会话的其余时间设置默认配置文件和／或区域。“切换到 prod”“使用 us-west-2”。
aws_session_get	显示当前会话默认值，以及各值的来源（session/env/default）。
aws_session_clear	移除会话配置文件／区域覆盖设置，让环境变量／默认值重新生效。不带参数时会清除两者。
aws_list_profiles	列出 ~/.aws/config 中配置的配置文件，包括名称、区域和 SSO 元数据。在切换配置文件之前，或 SSO 错误提到一个你尚未见过的配置文件时使用。
aws_assume_role	使用当前身份调用 STS AssumeRole，并将临时凭证保存为 ~/.aws/credentials 中的新配置文件（mcp-<sessionName>）。用于跨账户访问。密钥／会话令牌会保留在磁盘上，不会返回给模型。可选的 timeoutMs（默认 120s）用于处理较慢的 SAML／credential_process 冷启动。
aws_call	运行任意 AWS API 操作。service: 's3api', operation: 'list-buckets'，可选的 params（PascalCase JSON）和可选的 query（JMESPath）。返回解析后的 JSON。手写的 CLI 命令（s3 cp/ls/sync、logs tail）以及将响应流式写入文件的操作（s3api get-object、bedrock-runtime invoke-model、bedrock-agentcore invoke-agent-runtime、lambda invoke）永远不接受 --cli-input-json，因此 aws_call 无法调用它们；错误信息会说明原因并指出替代方式（aws_lambda_invoke、aws_logs_tail、bedrock-runtime converse 或 shell）。Waiter 可通过 operation: 'wait <name>' 使用。Blob 类型的参数需使用 base64。
aws_paginate	获取分页列表／描述操作的一页结果。也支持 query。返回 nextToken/hasMore；使用令牌再次调用即可继续获取。
aws_logs_tail	获取一个日志组中最新的 CloudWatch Logs 事件（通过 aws logs filter-log-events 调用 FilterLogEvents），支持 since、filterPattern 和流名称筛选条件；返回按时间从早到晚排列的 {timestamp, logStreamName, message} 对象。结果受 maxEvents 限制（默认值为 500，最大值为 10000）：较繁忙的时间窗口会保留最新事件，并报告 truncated: true。在 AWS CLI 2.35.8+ 中，读取操作本身会在达到 maxEvents 后停止，因此截断时 totalEvents 为 null；较旧的 CLI 会扫描整个时间窗口并报告准确数量。接受调用所在区域中的日志组 ARN，并以 logGroupIdentifier 传入，因此跨账户监控账户可以使用源账户 ARN（需要 AWS CLI 2.9.15+）。
aws_logs_query	端到端运行 CloudWatch Logs Insights 查询：调用 StartQuery，轮询 GetQueryResults 直到终止状态，然后返回行；一次调用即可完成，无需分别启动、轮询和解读状态。接受 logGroupNames（1-50 个，可为裸名称或 ARN）、queryString（Logs Insights QL，或通过 queryLanguage 使用 PPL），以及与 aws_metrics_query 相同的 startTime/endTime 格式；时间窗口最多为 90 天，limit 默认值为 1000。返回的行会将 API 的 [{field, value}] 对展平为普通对象，并附带 statistics（recordsMatched/recordsScanned/bytesScanned）。费用按扫描的未压缩字节数计算，因此应先缩小时间窗口，再考虑扩大范围。超时或客户端取消时，查询不会停止；会返回 queryId，结果可在 7 天内继续获取。
aws_metrics_query	通过 GetMetricData 查询 CloudWatch 指标（现代的多指标／支持表达式的 API）。传入 queries: [{id, namespace, metricName, dimensions?, statistic?, period?}] 或基于表达式的查询；startTime/endTime 接受 ISO 8601 格式或相对时间简写（'15m'、'1h'、'1d'）。周期会根据时间范围自动选择。返回 {series: [{id, label?, timestamps, values, period?, statusCode?}], periodSeconds, profile, region, nextToken, hasMore, messages?}（完整的封装结构见 Stability）。
aws_resource_get	通过 Cloud Control API 使用 typeName 和 identifier 读取 AWS 资源（例如 AWS::Lambda::Function 和函数名称）。返回解析后的 Properties。
aws_resource_list	通过 CCAPI 分页列出指定类型的资源。每个条目返回 {identifier, properties}，并附带 nextToken/hasMore。
aws_resource_create	通过 CCAPI 创建 AWS 资源。此操作为异步操作，返回顶层的 requestToken 和 operationStatus。传入 awaitCompletion: true 可让服务端轮询至终止状态，并在一次调用中返回结果。
aws_resource_update	通过 CCAPI 使用 RFC 6902 JSON Patch 更新 AWS 资源。异步操作及 awaitCompletion 的用法与创建操作相同。
aws_resource_delete	通过 CCAPI 删除 AWS 资源。异步操作及 awaitCompletion 的用法与创建操作相同。此操作具有破坏性，请先确认 identifier。
aws_resource_status	通过 requestToken 轮询异步 CCAPI 请求。返回当前状态，并将 operationStatus、identifier、errorCode、statusMessage 平铺到顶层（PENDING / IN_PROGRESS / SUCCESS / FAILED / CANCEL_*）。
aws_resource_diff	对 CCAPI 更新执行试运行：获取当前状态，在内存中模拟 JSON Patch，并返回 {before, after, changes[]}。不会向 AWS 发送任何变更。支持 RFC 6902 的 add/remove/replace 子集；add 会自动创建缺失的对象父级，以匹配 CCAPI 的实际更新语义（因此即使 /Environment/Variables 尚不存在，像 /Environment/Variables/NEW_KEY 这样的补丁也能正常使用）。changes[i].after 反映第 i 个操作产生的结果（而非补丁完成后的最终状态），因此可以正确读取对同一路径执行的一系列操作。如果你想确认补丁是否会达到预期效果，请在调用 aws_resource_update 前先调用此工具。
aws_multi_region	并行跨 N 个区域运行相同的 AWS 操作。结构与 aws_call 相同，但需传入 regions: string[]。返回 {region, ok, data?, error?}[]，并附带 okCount/errorCount。部分失败属于预期情况（服务并非在所有区域都可用，权限也可能按区域限定）。每次调用最多支持 64 个区域，同时最多有 32 个请求在执行。
aws_multi_account	并行跨 N 个账户运行相同的 AWS 操作，并在每个账户中担任 roleName。每个账户的凭证在整个调用期间都保留在内存中，并传递给该次启动的进程，不会写入 ~/.aws/credentials。与之相反，使用 aws_assume_role 循环要么会为每个账户写入一个配置节，要么会反复覆盖同一配置节（如果遍历过程中途失败，还会将有效密钥留在磁盘上）。返回结构与 aws_multi_region 相同，只是用 accountId 替代 region；同样包含 5 MB 总量上限，且 okCount/errorCount 会在截断前计算。部分失败属于预期情况：某些账户中可能不存在该角色。
aws_script	运行一段简短的 JS 代码片段，用于编排其他工具并返回组合结果。沙箱提供 aws.call、aws.paginate、aws.paginateAll、aws.resource.{get,list,create,update,delete,status}、aws.logsTail、aws.metricsQuery、aws.iamSimulate、aws.multiRegion、aws.assumeRole、aws.docs.{search,read}，以及标准 JS 内置对象（JSON、Math、Date、Promise 等）和 console。上下文中不会绑定 require/import/process/fs/fetch/定时器。**这不是安全边界：**脚本在此服务自身的进程中运行，且仍可从脚本内部访问主机全局对象，因此 aws_script 的权限严格高于其他工具——其他工具受 AWS 和你的 IAM 策略限制，而此工具不受这些限制。只传入你愿意在本机亲自运行的脚本文本，切勿传入来自日志行、资源标签或任何其他 AWS 响应的文本。适用于“列出 X、为每项获取 Y、返回 Z”这类原本需要 N 次往返的流水线。使用 return <value> 返回结果。
aws_iam_simulate	模拟主体的 IAM 权限：主体 X 能否对资源 Z 执行操作 Y？此工具封装 iam simulate-principal-policy。每个（操作、资源）组合返回一条结果；如果省略 resources，则每个操作只返回一条资源为 * 的结果。结果包含 decision（allowed / explicitDeny / implicitDeny / unknown）、matchedStatementIds（决定结果的 IAM 语句）、missingContextValues（策略需要但你未提供的上下文键）、permissionsBoundaryDecision 和 organizationsDecision（AWS 按操作报告的值）。SCP 拒绝不会指出其语句，且仅由 SCP 引用的键不会报告为缺失——请在 contextEntries 中传入 aws:RequestedRegion 等值。“allowed”是必要条件，但并非充分条件：RCP、目标资源自身的策略、会话策略和 VPC 端点策略都不会纳入评估。请传入 IAM 角色 ARN，而非 aws_whoami 显示的 STS 会话 ARN。在有风险的操作之前使用，以避免收到 403；它可与 aws_call 失败后的 Suggestion 配合使用。调用方需要拥有 iam:SimulatePrincipalPolicy 权限。
aws_lambda_invoke	同步调用 Lambda 函数，并返回其响应负载以及解码后的执行日志尾部。aws_call 从结构上无法执行此操作——aws lambda invoke 要求将响应正文作为必需的位置输出文件传入，并且会拒绝 --cli-input-json——因此这是无需再运行第二个（Python）MCP 服务即可使用的唯一 Lambda 调用方式。解码后的 logTail 将通常需要的“调用 → 查找日志组 → 获取日志尾部 → 希望日志窗口能覆盖它”流程合并为一次调用。非空的 functionError 表示函数的 HANDLER 抛出了异常：调用本身仍然成功，因此 ok 为 true，抛出的错误会出现在 payload 中。调用最多只会发送一次：此工具会关闭 CLI 的自动重试，因为重试会再次运行函数。timeoutMs 是等待函数的时长（默认值为 60s，最大为 900000）。被限流的调用并未运行，可以安全重试；发生超时后，错误信息会说明调用是否已发送。
aws_docs_search	搜索 AWS 实时文档（即 docs.aws.amazon.com 搜索框背后的服务）。返回按相关度排序的 {title, url, summary, excerpt}。每条结果还包含本地计算的 lexicalMatch，响应则包含 queryTerms / termsMatchedNowhere / bestLexicalOverlap / lowRelevance——该服务总会返回一整页模糊匹配结果，且不会说明“没有合适的匹配项”，因此这些值是判断查询是否一无所获的唯一信号。可用于查找模型可能不熟悉的服务／API／概念的相关文档页面，例如新服务、近期变更的 API 和确切的参数名称。
aws_docs_read	获取 https://docs.aws.amazon.com/...html 页面并以 Markdown 格式返回。会移除导航栏／Cookie 横幅／反馈等界面元素。长页面可通过 startIndex 和 maxLength 分页；响应会附带 hasMore 和 nextStartIndex。通常传入从 aws_docs_search 获取的 URL。

安装

添加到 MCP 客户端配置中（例如 .mcp.json）：

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "@yawlabs/aws-mcp@latest"]
    }
  }
}

请保留键名 aws（不要使用 aws-mcp 以外的名称）。AWS 的 aws configure agent-toolkit 向导会使用 aws-mcp 注册其托管服务，并且会将已有的 aws-mcp 条目报告为已配置，而不会检查该条目运行的内容。

-y 标志可实现每次会话加载时自动更新：每次 MCP 客户端启动该服务时，npx 都会检查注册表中的最新 @yawlabs/aws-mcp，并在有更新时下载。首次在全新缓存中启动会增加约 100-500 ms；后续启动会使用 npm 缓存（元数据的典型新鲜度窗口：5 min），增加约 50 ms 或更少。服务启动后，工具调用不会产生自动更新开销——检查仅在启动或重新启动时触发。无需单独安装；-y 同时涵盖首次安装和后续更新。

如果你更愿意固定特定版本（不自动更新，但启动时完全没有开销），请全局安装，并将配置指向已安装的二进制文件：

npm install -g @yawlabs/aws-mcp

{
  "mcpServers": {
    "aws": {
      "command": "aws-mcp"
    }
  }
}

需要新版本时，你必须手动运行 npm install -g @yawlabs/aws-mcp@latest。

会话示例

你让助手检查一个暂存存储桶，但 SSO 令牌刚好过期。助手会怎么做（以及你会看到什么）：

You:    "How many objects are in the staging-artifacts bucket right now?"

Claude: (calls aws_whoami) -> SSO session expired for profile 'staging'.
        (calls aws_login_start with profile='staging')
        "Your SSO token expired. Open
         https://device.sso.us-east-1.amazonaws.com/
         and enter code: ABCD-EFGH
         I'll wait."

You:    *click, authenticate in your browser*

Claude: (calls aws_login_complete with the sessionId)
        (calls aws_call with service='s3api', operation='list-objects-v2',
                         params={ Bucket: 'staging-artifacts' },
                         query='KeyCount')
        "There are 4,182 objects in staging-artifacts."

SSO 流程只需点击一次。无需切换上下文，想着“浏览器没打开，让我在终端里运行”。

对于更长的列表——任何可能超过 MCP 主机输出限制的内容（该限制远低于此服务的 5 MB 上限）——助手会使用 aws_paginate：

(calls aws_paginate with service='ec2', operation='describe-instances',
                        maxItems=50,
                        query='Reservations[].Instances[].{Id:InstanceId,State:State.Name}')
-> returns one page + a nextToken; Claude calls again until hasMore=false

query（JMESPath）会在服务端精简响应——如果只需要两个字段，典型的 describe-instances 结果会从数 MB 缩减到数 KB。

对于“创建此资源并在就绪时告知我”，aws_resource_create 配合 awaitCompletion: true，可将常见的“创建后轮询”循环合并为一次工具调用：

(calls aws_resource_create with
   typeName='AWS::SSM::Parameter',
   desiredState={Name: '/my/param', Type: 'String', Value: 'hello'},
   awaitCompletion: true)
-> server polls get-resource-request-status until SUCCESS / FAILED / CANCEL_COMPLETE
   and returns the terminal ProgressEvent in one call

aws_resource_update 和 aws_resource_delete 也采用相同的形式。省略 awaitCompletion（或将其设为 false），即可使用默认的触发后轮询行为——适合启动长时间运行的更新、稍后再查看的情况。

对于“应用之前先预览补丁”：

(calls aws_resource_diff with
   typeName='AWS::Lambda::Function',
   identifier='my-fn',
   patchDocument=[{op: 'replace', path: '/MemorySize', value: 1024}])
-> returns { before: {MemorySize: 256, ...}, after: {MemorySize: 1024, ...},
              changes: [{op: 'replace', path: '/MemorySize', before: 256, after: 1024}] }

不会向 AWS 发送任何更改；Agent 可以在调用 aws_resource_update 前验证补丁。

对于批处理工作流，aws_script 可将 N 次工具调用合并为一次：

(calls aws_script with code=`
   const listed = await aws.resource.list({ typeName: "AWS::Lambda::Function" });
   const big = [];
   for (const r of listed.resources) {
     const cfg = await aws.resource.get({
       typeName: "AWS::Lambda::Function", identifier: r.identifier });
     if (cfg.properties.MemorySize > 1024) {
       big.push({ name: cfg.properties.FunctionName, mem: cfg.properties.MemorySize });
     }
   }
   return big;
`)
-> one round-trip; the agent gets the filtered list without N intermediate tool calls

对于多区域读取：

(calls aws_multi_region with
   service='ec2', operation='describe-instances',
   regions=['us-east-1','us-west-2','eu-west-1'],
   query='Reservations[].Instances[].InstanceId')
-> {okCount: 3, errorCount: 0, results: [{region, ok, data}, ...]}

要求

• Node.js 22+（或 oam.js——参见 运行时）
• PATH 中有 AWS CLI v2。所有与 AWS 通信的工具都会调用它（除 aws_docs_*、aws_session_* 和 aws_list_profiles 外），因此你安装的 CLI 决定了可访问的服务、操作和参数。不强制要求最低版本：
  • 建议使用 2.22.0+。 该版本新增了 --use-device-code，此服务需要它来确保 SSO 短代码流程正常工作。较旧的 2.x 版本仍可使用——服务会检测版本并进行适配。
  • 基于 2.34.3 开发并测试。 CLI 本身会在发送请求前拒绝任何比你的 CLI 更新的内容：未知服务或操作会显示为“invalid choice”（错误随后会提示升级），新参数则显示为 Unknown parameter in input。对于通过 AWS 安装程序或安装脚本安装的 CLI，可使用 aws update（CLI 2.36.0+）升级；否则请使用安装程序或你的软件包管理器。
  • 安全性，截至 2026-09： CLI 2.35.3 或更高版本已修复所有已公布的 AWS CLI v2 安全公告（GHSA-747p-wmpv-9c78、CVE-2026-13769、CVE-2026-18654）。此服务无法触及任何受影响路径：这四个命令（emr ssh/socks/put/get、codeartifact login、deploy register、iam create-virtual-mfa-device）都没有注册 --cli-input-json，而 aws_call 只有通过它才会传递参数；第三项安全公告涉及选择启用的 cli_history 数据库，此服务从未启用该功能。不过，你确实会与计算机上的其他程序共用这个 CLI 安装。建议查看安全公告列表，确认是否有更新的公告：v2 以安装程序的形式发布，因此依赖项扫描器永远不会报告它。
  • 不支持 AWS CLI v1；它于 2026-07-15 进入维护模式，并将于 2027-07-15 终止支持。
• CLI 已可使用的 AWS 配置文件——请参见 环境，了解如何选择配置文件。SSO / IAM Identity Center 配置文件还可以使用设备代码重新登录工具。

运行时

此服务可在 oam.js 和 Node 上未经修改地运行，并且 启动器绝不会在低于 0.18.0 的 oam 上提供服务，而是选择能找到的、 达到或高于该最低版本的最新 oam 二进制文件。已在 oam 0.18.0 （aarch64-pc-windows-msvc）上验证：完成列出全部 28 个工具的 MCP 握手、调用本地工具，以及下文所述的 aws_script 沙盒行为。

oam 0.18.0 是最低版本。 启动器会选择能找到的、达到或高于该版本的最新 oam，绝不会在更旧的版本上提供服务；如果找不到，则回退到 Node （AWS_MCP_RUNTIME=oam 会将其变为硬性错误）。此处设置最低版本很重要： 0.9.0 之前的版本会通过 shell 执行 child_process.execFile 的参数， 会接受 exec 的 timeout 但忽略它，并会将 stdio: 'inherit' 当作 'pipe' 处理；而此服务几乎每次调用工具都会通过 shell 调用 aws CLI。

要在 oam 下运行，请将 MCP 客户端的 command 指向它：

{
  "mcpServers": {
    "aws": {
      "command": "oam",
      "args": ["run", "/path/to/aws-mcp/dist/index.js"],
      "env": { "AWS_PROFILE": "my-sso-profile", "AWS_REGION": "us-west-2" }
    }
  }
}

请在自己的硬件上测量启动时间。 MCP 客户端每个会话都会冷启动一次此服务， 因此启动开销才是实际需要付出的成本。以下数据是在 oam 0.8.2 上测得的， 远早于当前的 0.18.0 最低版本，且此后未重新测试，因此请勿将其视为当前排名。 在完成 initialize + tools/list 握手的情况下，10 次预热运行的中位数：

运行时	冷启动
node dist/index.js	359 ms
oam run dist/index.js	650 ms
oam run src/index.ts（无需构建步骤）	947 ms
已发布的 aws-mcp 命令会优先使用它找到的最新 oam（见 Environment 中的 AWS_MCP_RUNTIME）。如果没有安装 oam，几乎不会产生额外开销：发现过程只检查文件是否存在，不会启动子进程；回退方案则会在 npm 已启动的 Node 进程内运行服务。不过，如果安装了 oam，该命令会先启动 Node，对找到的每个 oam 二进制文件运行 --version，以选出最新版本，然后才启动 oam，因此始终比使用上述配置直接将客户端指向 oam 更慢。AWS_MCP_RUNTIME=node 可完全跳过 oam。

对于此仓库，还有两处适合使用 oam；两者都需主动选择，且都不会影响已发布的 npm 包：

• npm run check:oam —— 通过 oam check 进行类型检查（原生 TypeScript 7 tsgo）。实测耗时 约 1.0 秒，而 tsc --noEmit 耗时约 3.8-4.7 秒；两者解析相同的 tsconfig.json，检查相同的文件（包括测试文件，这一点已通过在测试文件中故意加入类型错误，并确认两者都会报错验证）。npx tsc --noEmit 仍是可移植的默认方案。
• npm run build:binary:oam —— 通过 oam compile 构建独立二进制文件。实测在 win32-arm64 上大小为 58.60 MB，其中包括约 493 KB 的嵌入式 V8 字节码。输出到 bin/<platform>-<arch>/，由发布暂存脚本处理。如果重新分发此二进制文件，其中包含 oam 运行时，因此请随附 oam 的 LICENSE、NOTICE 和 THIRD_PARTY_LICENSES.md。

源码有意保持与运行时无关：任何地方都没有 oam: 导入，测试也继续使用 node:test。这才确保 Node 回退方案确实可用，而非名义上的支持。

如果在 oam 下运行 aws_script，有一个值得注意的行为差异：Node 会在 node:vm 上下文中遵循 codeGeneration: { strings: false } 设置，因此 eval 和 Function 会抛出异常；oam 则不会，因此它们可以正常使用。针对 oam 0.18.0 重新测量后，这一差异依然存在——在沙箱内，oam 下的 eval('1+1') 返回 2，Function('return 7')() 返回 7；而在 Node 下，两者都会引发 EvalError，因此应将其视为长期存在的差异。不过，重要的隔离措施不受影响：在 oam 下，Function('return this')() 会返回一个全局对象，其中 process 和 require 均为 undefined；Function('return require') 则会抛出异常。因此，脚本无法通过在函数体中编写相同代码做不到的事来获益。aws_script 从来就不是安全边界（见其说明）；真正的防护是被遮蔽的全局变量列表，而非该标志。

请注意，任何 oam 调用都会在工作目录的 oam/ 中写入字节码缓存；该目录已列入 .gitignore。

环境

变量	默认值	用途
AWS_PROFILE / AWS_DEFAULT_PROFILE	default	工具调用未指定 profile 时使用的配置文件。AWS_DEFAULT_PROFILE 是旧版名称。如果两者均已设置，则优先使用 AWS_PROFILE，与 AWS CLI v2 一致（独立运行的 botocore 和 boto3 会优先检查 AWS_DEFAULT_PROFILE）。空值视为未设置。
AWS_REGION / AWS_DEFAULT_REGION	us-east-1	工具调用未指定 region 时使用的区域。如果两者均已设置，则优先使用 AWS_REGION。
AWS_SHARED_CREDENTIALS_FILE	~/.aws/credentials	aws_assume_role 写入所创建配置文件的位置。会遵循此设置（并像 botocore 一样展开 ~），确保写入的文件与 CLI 后续读取的文件相同。
AWS_MCP_AWS_CLI	未设置	要运行的 aws 可执行文件的绝对路径，用来替代在 PATH 中找到的版本。适用于从 GUI 启动的 MCP 宿主，因为它们通常不会继承 shell 的 PATH；而 AWS 推荐的安装程序现在默认将其安装到 macOS 和 Linux 上的 ~/.local/bin，此类宿主通常无法找到该目录。使用 command -v aws（macOS/Linux）或 where.exe aws（Windows）查找路径。在 Windows 上使用 Git Bash 时，请使用 where.exe aws，而不是 command -v aws：后者会输出 POSIX 风格的路径（/c/Program Files/...），此变量会拒绝该路径，因为它必须是原生绝对路径。此设置适用于所有调用以及 aws sso login。路径必须是绝对路径；在 Windows 上必须指向 aws.exe：没有 shell 就无法启动 .cmd 或 .bat 垫片。若设置的值无法使用，每次调用都会失败，并显示提及此变量的消息，而不会悄悄运行与你配置不同的 CLI。若未设置，服务会遍历 PATH 中的绝对路径目录；绝不会运行工作目录中的 aws。

已发布的 aws-mcp 命令运行的启动器（bin/aws-mcp.mjs，也是 npx @yawlabs/aws-mcp 启动的内容）还会读取另外两个变量。它们用于选择运行时，与 AWS 无关；若客户端直接指向 dist/index.js，则会绕过这两个变量。运行在 oam 上会带来哪些变化，请参阅运行时。

变量	默认值	用途
AWS_MCP_RUNTIME	auto	auto：如果启动器当前运行在 0.18.0 或更高版本的 oam 上，则在该 oam 上提供服务；否则，使用能找到的最新 0.18.0 或更高版本的 oam 二进制文件运行（参见 OAM_BIN）；若没有，则使用 Node。如果 oam 宿主版本低于 0.18.0，它绝不会自行运行此服务，而是交由最新的可用 oam 运行；若没有，则交由 PATH 中的 Node 运行；两者都不存在时则报错退出。若 OAM_BIN 无法使用，stderr 会始终指出该变量；只有找不到可用 oam 时，才会指出被跳过的其他 oam 二进制文件。oam：行为相同，但不会回退到 Node，而是报错退出。node：始终使用 Node——在 npx 下进程内运行；客户端通过 oam run 启动命令时，则交由 PATH 中的 Node 运行。不区分大小写，其他任何值都按 auto 处理。
OAM_BIN	未设置	优先于自动查找使用的 oam 二进制文件路径，版本必须为 0.18.0 或更高。如果文件不存在、版本较旧或无法运行，启动器会在 stderr 中说明，然后继续自动查找。自动查找会先检查设置了 OAM_INSTALL_DIR 时指定的目录（即 oam 安装程序的目标目录），然后检查已安装位置（Windows 上依次为 %LOCALAPPDATA%\oam\bin 和 ~/.oam/bin；其他系统上为 ~/.oam/bin），再检查 PATH；启动器会向找到的每个 oam 查询其版本，并使用版本最新的一个；若版本相同，则优先使用已安装的副本。在 Windows 上，只有 oam.exe 才算可用；绝不会运行 oam.cmd / oam.bat 垫片，找不到可用 oam 时会在 stderr 中指出该垫片。设置 AWS_MCP_RUNTIME=node 时，或当前已运行在 0.18.0 或更高版本的 oam 上时，此变量会被忽略。
服务在每次 aws 调用时设置的内容。 每个 aws 子进程都会获得以下设置，这些设置会覆盖你的 shell 和 ~/.aws/config 中的设置，因为每项都会改变本服务解析的输出：AWS_CLI_ERROR_FORMAT=enhanced（CLI 2.34.0 的 json/yaml/text/table 错误格式会移除 errorKind 分类所读取的 An error occurred (Code) 文本）、AWS_CLI_AUTO_PROMPT=off（自动提示需要控制台，从 MCP 主机发起的每次调用都会失败，包括 aws sso login）、AWS_CLI_OUTPUT_ENCODING=utf-8 和 PYTHONUTF8=1（在 Windows 上，否则 CLI 会使用 ANSI 代码页写入，遇到该代码页之外的任何字符都会失败）；在 Windows 上还会设置 NoDefaultCurrentDirectoryInExePath=1（这样 CLI 自己的辅助程序，例如 session-manager-plugin，就绝不会从工作目录运行）。这些是环境变量而非标志，因此不认识其中某个变量的旧版 2.x CLI 会直接忽略它。一个副作用仅影响 Windows：在早于 2.25.0 的 CLI 上，PYTHONUTF8=1 还会让 CLI 以 UTF-8 读取 ~/.aws/config 和 ~/.aws/credentials，因此，以旧版 Windows 代码页保存的文件中若有非 ASCII 字符，就会导致解析失败——请将文件重新保存为 UTF-8，或更新 CLI。在 macOS 和 Linux 上，这里固定该设置没有影响，因为不存在需要切换的 ANSI 代码页：在 linux/arm64 上使用 aws-cli 2.36.49 测得，~/.aws/config 中的 cp1252 字节在 PYTHONUTF8 未设置、设为 =0 和 =1 时，以及在 LC_ALL=C 和 LC_ALL=POSIX 下，都会以相同方式导致解析失败；同一字符若以 UTF-8 编码，则在所有这些情况下都能解析。带有 params 的调用还会传入 --cli-binary-format base64，因此 blob 类型的 params 始终采用 base64 编码，无论你的配置如何。以下设置会有意沿用你的配置：重试模式和最大尝试次数、cli_timestamp_format（在 CLI 中只能通过配置设置；wire 会返回 epoch 数字而非 ISO 字符串）、cli_history，以及端点、代理和 CA 设置。

如果你通过 SAML（Okta / Azure AD / ADFS）或自定义的 credential_process 进行身份验证，请将 AWS_PROFILE 设置为对应配置文件。

每次调用都会先解析配置文件名称——显式的工具 profile 参数 -> 由 aws_session_set 设置的会话配置文件 -> $AWS_PROFILE -> $AWS_DEFAULT_PROFILE -> 字面值 default——然后将其作为 --profile <name> 传给 CLI。不存在“无配置文件”模式，只有一个例外：aws_multi_account 仅在其 sts:AssumeRole 调用中使用解析出的配置文件；随后，每个账户的操作都会使用该账户的角色凭证运行，不带 --profile 标志。在选定的配置文件中，CLI 自身的凭证链会照常解析：credential_process、SSO 会话（包括 sso_session 块和内联的 sso_start_url）、通过 source_profile / role_arn 进行角色链式切换、存储在 ~/.aws/credentials 中的静态密钥、容器凭证以及 IMDS。

例外——不会使用环境变量中的静态密钥。 由于始终会显式传入配置文件，botocore 会从凭证链中移除环境变量凭证提供程序，因此不会读取你在 shell 中导出的 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN。（容器凭证和 IMDS 不受影响——它们位于凭证链后续位置，不受配置文件限制。）如需使用静态密钥，请将其放入 ~/.aws/credentials 的某个配置文件段中，并将 AWS_PROFILE 指向该配置文件，而不是导出这些环境变量。

通过代理或使用私有 CA

aws_docs_search 和 aws_docs_read 会从此进程通过 HTTPS 获取内容，因此它们是企业网关会影响的两个工具。现在，报错会指出问题原因，而不是归咎于 AWS 后端；解决方法是在 MCP 配置中添加 env 条目——而不是在 shell 中导出变量，因为下面两个变量都在进程启动时读取，且 MCP 客户端会自行启动服务。

变量	用途
NODE_EXTRA_CA_CERTS	存放网关 CA 证书的 PEM 文件路径；如果 TLS 拦截导致获取失败，并出现自签名或未知颁发者错误，请使用此变量。
NODE_USE_SYSTEM_CA=1	使用操作系统的证书存储，而不指定文件（Node 22.19+）。
HTTPS_PROXY / https_proxy	用于获取内容的代理。在 Node 中，除非同时通过 NODE_USE_ENV_PROXY=1 或 --use-env-proxy 启用代理（Node 22.21+，也可在 NODE_OPTIONS 中指定），否则会忽略此变量；否则请求会直接发出，仅允许代理访问的网络则只会超时。在 oam 上运行时，无需启用代理即可使用此变量。

AWS CLI 是独立进程，有自己的规则，因此，在同一网关后使用 credential_process、SSO 登录或任何 aws_call，都遵循 AWS CLI 自身的代理配置（HTTP_PROXY / HTTPS_PROXY 和 AWS_CA_BUNDLE），而不是上面的 Node 变量。这类失败现在也会提供相应的解决方法。

如果调用未指定 profile，未调用 aws_session_set，AWS_PROFILE 和 AWS_DEFAULT_PROFILE 均未设置为非空值，并且 ~/.aws/config 和 ~/.aws/credentials 均未定义 default 配置文件，则 CLI 会因 ProfileNotFound 拒绝 --profile default，工具会将其报告为 no_creds 错误。请在 MCP 配置中将 AWS_PROFILE 设置为你平时使用的配置文件。

SSO 登录流程的工作原理

1. Claude calls aws_login_start({ profile: "prod" })
2. Server spawns: aws sso login --no-browser --use-device-code --profile prod
   (--use-device-code keeps the CLI on the device grant; without it, 2.22.0+
    prints an authorize URL with no short code to surface)
3. Server parses the URL + code from stdout, returns them to Claude
4. Claude surfaces: "Open https://device.sso.us-east-1.amazonaws.com/ and enter ABCD-EFGH"
5. You click — browser opens in your own user session — auth in ~10 seconds
6. Claude calls aws_login_complete({ sessionId })
7. Tool returns your new identity. Back to work.

令牌会缓存到 ~/.aws/sso/cache/<hash>.json，方式与常规的 aws sso login 相同，因此 AWS CLI、SDK 以及你设备上的所有其他工具都能自动读取它。

为什么此服务必须在本地运行（而不能运行在 mcp.hosting 上）

SSO 令牌存放在你的设备上的 ~/.aws/sso/cache/ 中。远程 MCP 服务无法读取这些令牌。因此，这是一个 stdio 服务，而不是托管服务。这是 AWS SSO 的限制，并非 mcp.hosting 的局限。

稳定性

从 1.0 版开始，此软件包遵循语义化版本规范。0.x 系列是稳定前的收紧阶段——重大变更会记录在 CHANGELOG.md 中，但不一定等到主版本号提升后才发布。

1.x 中稳定的内容（以下任何变更均为重大变更，必须提升主版本号）：

• 工具名称——上文「工具」表格中列出的 28 个工具名称不会重命名或移除。

• 工具注解——readOnlyHint、destructiveHint、idempotentHint、openWorldHint。这些注解会告知 MCP 主机如何限制调用；若无提示地更改它们，会破坏主机 UI。请注意保证方向：如果此前的注解低估了工具的能力，补丁版本可以收紧注解（使其更加谨慎）——v2.0.1 正是出于此原因，将 aws_call、aws_multi_region 和 aws_resource_update 的 destructiveHint 设为 true。在主版本之外不会放宽这些注解。如果你的主机根据这些注解抑制确认提示，请将 aws_call 和 aws_multi_region 视为能够调用调用者的 IAM 身份有权限使用的任何 AWS API，包括删除操作。

• 必需输入字段——各工具的必需字段结构不会更改或移除。可能会添加新的可选字段。

• 各工具成功响应的信封结构——{ok: true, data} 响应中的 data 对象，具体如下：

  • aws_call -> {command, commandArgv, result}
  • aws_paginate -> {command, result, nextToken, hasMore}
  • aws_multi_region -> {service, operation, regionCount, okCount, errorCount, results: [{region, ok, data?, command?, error?, errorKind?, truncated?}]}（聚合响应有大小上限；超过预算的条目会保留 region/ok，但移除 data，并标记为 truncated: true。错误条目绝不会被移除；okCount/errorCount 在截断前计算，因此始终反映调用实际结果，而非截断后保留的内容。）
  • aws_multi_account -> {service, operation, roleName, accountCount, okCount, errorCount, results: [{accountId, ok, data?, command?, error?, errorKind?, truncated?}]}；达到 5 MB 聚合上限时，还会包含 truncated、truncatedAccounts 和 maxTotalResultBytes。字段与 aws_multi_region 一一对应，只是用 accountId 代替 region；其中 okCount/errorCount 同样在截断前计算，因此反映调用实际结果，而非截断后保留的内容。重复的账户 ID 会合并，因此 results.length 可能小于 accounts.length；请使用 accountCount。凭证绝不会写入 ~/.aws/credentials，也不会出现在 command、error 或 rawBody 中。
  • aws_whoami -> {account, userId, arn, profile, region, ssoToken: {expiresAt, minutesLeft, startUrl?} | null}（如果缓存的令牌未记录 startUrl，则省略该字段）
  • aws_login_start -> {sessionId, profile, verificationUrl, userCode, instructions, reused?}（为同一配置文件重新展示进行中的登录时，reused: true）
  • aws_login_complete -> {loggedIn, account, userId, arn, profile, region, ssoToken}（ssoToken 结构与 aws_whoami 相同，包括可选的 startUrl）
  • aws_refresh_if_expiring_soon -> **根据分支返回两种结构之一：**当缓存令牌剩余时间超过 thresholdMinutes 时，返回 {status: "ok", minutesLeft, expiresAt, profile}；刷新正在进行时，返回 {status: "refreshing", reason, sessionId, profile, verificationUrl, userCode, reused?, instructions}。请根据 status 判断。
  • aws_assume_role -> {profile, credentialsPath, expiration, assumedRoleArn, assumedRoleId, sourceProfile, hint, warning?}（仅当目标配置文件已存在且其三个凭证键被原位覆盖时，才会包含 warning；若设置了 AWS_SHARED_CREDENTIALS_FILE，credentialsPath 会遵循该变量）
  • aws_list_profiles -> {configPath, profiles: [{name, region?, ssoStartUrl?, ssoRegion?, ssoSession?, isSso}]}
  • aws_session_get / aws_session_set / aws_session_clear -> {profile, region, profileSource, regionSource}，其中 *Source 为 "session" | "env" | "default"。三者返回相同结构（set/clear 返回变更后的状态）。
  • aws_resource_get -> {command, typeName, identifier, properties, propertiesRaw?}
  • aws_resource_list -> {command, typeName, resources: [{identifier, properties, propertiesRaw?}], nextToken, hasMore}（如果某条条目的 Properties 字符串无法解析，就会随该条目返回 propertiesRaw，与 aws_resource_get 一致）
  • aws_resource_create / _update / _delete / _status -> 扁平化提升字段的结构 {command, requestToken, operationStatus, identifier, errorCode, statusMessage, retryAfter, progressEvent}；传入 awaitCompletion: true 时，还会包含 awaited: {attempts, elapsedMs} 块；若传入 awaitCompletion: true 但未返回可用于轮询的请求令牌，则会包含 awaitSkipped 字符串
  • aws_resource_diff -> {command, typeName, identifier, before, after, changes, changeCount}
  • aws_logs_tail -> {command, logGroupName, logGroupIdentifier, since, eventCount, totalEvents, truncated, events}。每个事件的结构为 {timestamp, logStreamName, message}：timestamp 是带毫秒的 ISO 8601 UTC 时间，message 是原样返回的事件文本；如果事件返回时缺少这三个成员中的任何一个，相应值会为 null，该事件会保留而非丢弃，因此 eventCount 与服务返回的事件数一致（实际的 CloudWatch 会发送全部三个字段；行为不同的端点可能不会）。events 按时间从旧到新排列，最多包含 maxEvents 条（默认为 500），并保留最新事件；eventCount 是 events 中的事件数，只有当窗口内事件数更多时，truncated 才为 true。totalEvents 是工具读取完整个窗口时窗口内的事件数；若提前停止，则为 null：在 AWS CLI 2.35.8+ 中，读取顺序为从新到旧，事件数超过 maxEvents 后就会停止，因此截断结果中的 totalEvents 为 null；旧版 CLI 或忽略 FilterLogEvents 的 startFromHead 的端点会读取整个窗口并报告准确数量。logGroupName 始终是纯组名；如果输入为 ARN，logGroupIdentifier 是发送给 FilterLogEvents 的 ARN（会移除末尾的 :*），否则为 null。
  • aws_logs_query -> {command, startCommand, profile, region, queryId, status, queryLanguage, logGroupNames, startTime, endTime, fields, rows, rowCount, statistics, truncated, polled: {attempts, elapsedMs}}。在 ok: true 分支中，status 始终为 "Complete"——其他所有终止状态（Failed、Cancelled、Timeout、无法识别的状态或缺失状态）都会返回 ok: false；maxWaitMs 超时和客户端取消也会返回 ok: false，两者都会在错误字符串中附带 queryId，因为错误信封没有 data。command 是最后一次 get-query-results 调用，startCommand 是 start-query 调用（其 --cli-input-json 负载会经过脱敏，因此不会回显查询文本）。rows 是 API 的 [{field, value}] 数组展平为普通对象后的结果；非字符串值会变为 null。fields 按首次出现顺序列出所有字段名；logGroupNames 是实际查询的解析后纯组名（输入为 ARN 时会提取并回显其名称）。响应未提供 queryLanguage 或 statistics 时，对应值为 null。当 rowCount 达到有效的 limit 时，truncated 为 true。此工具在任何情况下都不会在 AWS 端停止查询。
  • aws_metrics_query -> {command, profile, region, startTime, endTime, periodSeconds, series: [{id, label?, timestamps, values, period?, statusCode?}], nextToken, hasMore, messages?: [{code?, value?}]}（messages 为空时会省略；CloudWatch 返回或查询指定/继承了周期时，各序列会包含 label / period / statusCode；除非 CloudWatch 截断了响应，否则 nextToken 为 null 且 hasMore 为 false）
  • aws_iam_simulate -> {command, principalArn, summary: {allowed, denied, unknown, total}, results, marker, hasMore}（results 对 IAM 的每个 (action, resource) 组合各包含一个条目，数据取自 IAM 的 ResourceSpecificResults。未传入 resources 时，每个 action 返回一个 resource: "*" 条目；对于 AWS 不会按资源拆分结果的 action，则返回一个条目，其中包含 AWS 自身的 EvalResourceName（* 或该 action 的 ARN 模板）。summary 统计条目数。若 AWS 未提供按资源的 organizationsDecision 和 permissionsBoundaryDecision，则回退使用 AWS 的 action 级值；但 allowed 条目始终读取 "allowed"。unknown 统计缺失或无法识别决策的条目，避免将格式错误的响应静默归入 denied。CLI 会自行处理 IAM 分页，因此首次调用会完整返回——hasMore: false、marker: null；只有从 marker 继续调用时，两者才会携带游标，此时 summary 仅统计该页。）
  • aws_lambda_invoke -> {command, statusCode, functionError, executedVersion, payload, logTail}；仅当响应正文被截断时才会包含 payloadTruncated: true（否则省略该字段，使其表示异常标记，而非大小报告）。logTail 是函数的 LogResult，且已完成 base64 解码。非空的 functionError 仍然属于 ok: true：调用成功，但函数处理程序抛出了错误，抛出的错误位于 payload 中；调用失败（函数名称错误、无权限、限流或超时）才会返回 ok: false。调用绝不会发送多次；errorKind: "timeout" 表示未及时收到响应，错误消息会说明调用是否已发送（若已发送，函数可能已经运行或仍在运行）。
  • aws_script -> {result, logs, truncatedLogs, durationMs}，其中 result 是脚本 return 的任意内容（任何可序列化为 JSON 的值，包括 undefined）
  • aws_docs_search -> {query, count, results: [{title, url, summary?, excerpt?, lexicalMatch}], queryTerms, termsMatchedNowhere?, bestLexicalOverlap, lowRelevance, relevanceNote?}（只有当上游搜索后端返回 summary / excerpt 时才会包含这些字段。自 2.1.0 起提供的相关性字段由此服务在本地计算：查询词与结果标题/摘要/摘录之间的字面词汇重合度；它不是后端评分，也不是语义排名——只会为结果添加注解，不会重新排序。对于每个结果，lexicalMatch 的结构为 {overlap, matchedTerms, unmatchedTerms}；若查询没有可评分的词，则为 null，此时 bestLexicalOverlap 也为 null，且省略 termsMatchedNowhere。当最佳结果匹配的查询词不超过一半、任意查询词都未出现在任何结果中，或后端未返回结果时，lowRelevance 为 true。relevanceNote 是对 lowRelevance 判定或无可评分查询词情况的文字说明；无需说明时省略。）
  • aws_docs_read -> {url, cached, content, startIndex, endIndex, totalLength, hasMore, nextStartIndex}

• 错误信封——{ok: false, error: string, rawBody?: string, errorKind?: string, suggestion?: string}。error 字符串面向用户；其措辞尽力而为（见下文），而 errorKind 是稳定的机器可读部分——请参见下文的枚举。suggestion 提供针对已识别 AWS 错误代码的一行解决办法；该内容也会附加在 error 末尾，因此它是为程序化调用者提供的便利信息，而非额外信息。在传输中，错误结果是一个文本块，errorKind 独占首行：先是 errorKind: <kind>，接着换行，然后是 Error: <message>，再空一行，最后是存在且未被消息引用的 rawBody。未分类的失败会完全省略该行，并和之前一样直接以 Error: 开头。

• errorKind 枚举——"sso_expired" | "expired_creds" | "no_creds" | "invalid_creds" | "bad_input" | "spawn_failure" | "timeout" | "output_too_large" | "malformed_json" | "nonzero_exit" | "unexpected" | "cancelled"。它出现在两个不同的地方，规则各不相同。 在顶层错误信封中，对于每个封装 aws CLI 调用的工具——aws_call、aws_paginate、aws_logs_tail、aws_logs_query、aws_metrics_query、aws_iam_simulate、aws_lambda_invoke、aws_assume_role、aws_whoami、aws_login_complete 以及 aws_resource_* 系列。如果失败并未到达 CLI，则此处不会出现 errorKind，也不会使用默认值：例如工具自身的输入验证、aws_docs_* 的 HTTP 失败、客户端取消轮询。缺少 errorKind 时，应视为“未分类”，而不是 nonzero_exit。

  在扇出工具 results 数组的每个条目中——aws_multi_region 和 aws_multi_account。失败条目始终带有 errorKind，包括从未到达 CLI 的失败：两个工具都会将自身拒绝的条目（格式错误的区域名称、不是 12 位数字的账户 ID）归类为 bad_input，并将工作线程抛出异常的条目归类为 unexpected。unexpected 仅用于扇出场景——不会出现在顶层信封中；cancelled 也是如此，它表示客户端在工作线程领取任务前取消了请求，因此该条目从未尝试执行。对于 cancelled 条目，没有任何内容发送到 AWS；已经运行的条目保留其实际结果，并且数组仍涵盖完整的请求集合，因此 okCount/errorCount 不会将已取消的扫描误认为规模更小但成功的扫描。

  可能会添加新变体（仅增补）；现有变体不会重命名或改变用途。三种凭证类型有意区分，因为相应的补救措施各不相同：no_creds 表示未找到凭证，invalid_creds 表示已解析出凭证，但 AWS 拒绝了它们（密钥轮换后常见），expired_creds 表示临时会话已过期。expired_creds 不区分来源——AWS 会为 SSO 派生的会话、aws_assume_role 会话和 Web 身份会话返回相同的 ExpiredToken 包装，因此其消息会指出两种补救措施，而不会假定来源是 SSO；sso_expired 仅用于明确指出 botocore 的 SSO 令牌提供程序的错误。malformed_json 表示标准输出以 { 或 [ 开头，但解析失败，即响应被截断，而非 --query 可以合法生成的标量输出。

尽力而为（可能在次要版本或补丁版本中更改）：

• 错误消息措辞。 像“配置文件 'X' 的 SSO 会话已过期。请调用 aws_login_start...”这样的字符串可能会调整，以提高清晰度。应以 errorKind 或结构化信封为依据，而不是使用正则表达式匹配 error 文本。
• suggestion 措辞——根据已识别的 AWS 错误代码生成的一行补救建议。是否提供建议取决于错误代码，但具体句子可能会调整；应根据 errorKind 分支判断，而不是依据这段文本。该建议也会在 error 的末尾重复出现，因此同时读取两者的调用方不得重复打印。
• rawBody 内容——底层 aws CLI 的原始标准错误/标准输出，仅用于诊断。其格式取决于你安装的版本所使用的 CLI 输出。
• command 字符串——与结果一同显示的人类可读命令。参数数组的顺序和精确的脱敏占位符格式（<redacted len=N>）可能会变化。该字符串适用于运行服务的主机所用的 shell：POSIX shell，或 Windows 上的 PowerShell。它不适用于 cmd.exe，因为无论如何引用，&、| 和换行符都仍会生效；也不适用于 Windows 上的 Git Bash，因为包含单引号的值会丢失引号，导致传入的内容错误（Buckets[?Name=='prod'].Name 是实际可能遇到的情况；它会变成无效的 JMESPath，而不是任何能运行的内容）。 请使用 commandArgv，不要解析 command。 每个携带 command 的信封也会携带 commandArgv：同一调用的精确、未加引号的词元数组——第 0 项是显示的二进制文件，之后每个参数各占一项——并且会以相同方式进行脱敏，因为字符串是从数组生成的。服务器实际启动的就是它（整个过程中不会涉及 shell），因此无需拆解，也不会被你意料之外的 shell 重新解释。如果需要运行，请按你自己的 shell 语法重新加引号；字符串形式便于阅读，数组才是约定。
• 工具的描述——呈现给模型的文字。收紧这些描述不会造成破坏性变更。

**弃用政策：**破坏稳定的结构需要提升主版本号。弃用会先在次版本中引入（旧结构继续有效，同时提供新结构），并计划在下一个主版本中移除。弃用和移除都会记录在 CHANGELOG.md 中。

开发

npm test 会运行单元测试和集成测试。集成测试套件会启动一个本地 fake-aws 子进程来模拟 AWS CLI——无需 AWS 凭证或网络访问。名为 *.realcli.test.ts 的测试套件会将 fake 与真实 CLI 进行对照：它们会驱动 PATH 上的 AWS CLI v2，连接到进程内运行于 127.0.0.1 的端点，使用临时密钥，并将其他所有地址路由到无响应的代理，因此不会有任何流量离开本机。只需启动 CLI 几次的测试会在每次 npm test 时运行；如果未安装 CLI v2，则会跳过。这些会等待真实超时和重试的测试还需要设置 AWS_MCP_REAL_CLI_TESTS=1，该变量由 release.sh 设置。只有由 AWS_MCP_LIVE_TESTS 环境变量控制、需要真实 AWS 凭证的实时测试，才会在标准的 npm test 运行中跳过。

许可证

MIT