AWS Resource MCP

本地 MCP 服务器，使用 Python 开发，用于以只读模式查询 AWS 账户中的真实资源。

状态

第 9 阶段已实现。该服务器结合了统一清单、保守的活动分析、显式诊断、经济分析以及根据实际操作日志生成的最小权限 IAM 策略。

Related MCP server: aws-mcp-server

预期范围

• 通过 stdio 进行本地 MCP 传输。

• 主要区域：eu-west-1。

• AWS 查询仅限只读且遵循最小权限。

• 可用工具：health_check()、listar_recursos_aws()、analizar_actividad_recursos()、diagnosticar_cobertura_aws()、analizar_riesgo_costes()、revisar_free_tier() 和 consultar_costes_aws()。

• Cost Explorer 在收到针对确切请求的临时同意之前保持锁定。

• 不在 AWS 上部署，也不进行持续交付。

可靠性

第 10 阶段加入了本地集成、契约、安全、性能和 MCP 协议测试。清单在每次 SDK 调用前还会应用 AWS_MCP_MAX_REQUESTS_PER_TOOL（默认 250）；当预算耗尽时，会保留结果并返回 partial_request_budget_exhausted。

持续集成在每个 pull request 中执行格式化、lint、编译、确定性 IAM 验证和本地测试。它不配置 AWS 凭据，也不执行 AWS 操作。

与 Codex 配合使用

Codex 是主要客户端。通过 stdio 使用包入口点 uv run aws-resource-mcp，在仓库外部配置任何 AWS 配置文件，并以自然语言问题开始，例如“我在 eu-west-1 中有哪些资源？”。当响应为 partial_pending_consent 时，Codex 必须解释确切的操作并等待明确批准；它从不创建持久同意。请参阅 Codex 集成 和 演示。

发布 v0.1.0

第一个版本已准备好接受审查：包含只读保护、临时同意、Codex 集成和 CI。请参阅 发布检查清单 以在本地验证并运行安全演示。

开发

项目使用 uv 和 Python 3.12 或更高版本管理。

安装依赖

uv sync

运行服务器

uv run aws-resource-mcp

出于诊断目的，也可以作为模块运行：

uv run python -m aws_resource_mcp.server

服务器使用 stdio：它期望 MCP 客户端通过标准输入和输出交换消息。可以使用 SDK 中包含的工具通过 MCP Inspector 打开它：

uv run mcp dev src/aws_resource_mcp/server.py

运行测试

uv run pytest

生成并验证 IAM 策略

uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --check

生成过程是本地、确定性的，不使用凭据。项目不会在 AWS 中创建或修改角色或策略。策略区分免费操作、需要同意的读取操作以及组合最大值；IAM 权限永远不会取代应用程序的同意。

运行 AWS 清单

在实际诊断之前，检查本地配置将解析为哪个身份：

aws sts get-caller-identity

然后，在默认区域 eu-west-1 中运行清单：

uv run python -m aws_resource_mcp.aws.inventory

区域和共享配置文件是可选的：

uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile example

项目中不保存密钥。Boto3 使用其标准的凭据解析链；如果指定了 AWS_PROFILE 或 --profile，则只会选择一个必须已存在于仓库之外的配置文件。

MCP 工具

health_check

health_check(check_aws=True) 将本地健康状态与 AWS 的可访问性分开。不带参数时，最多执行一次受保护的 STS 调用；使用 check_aws=false 时不使用网络。返回版本、传输方式、已注册的工具和适配器、区域、经济策略以及零计费操作。其状态为：

• ok：服务器和配置有效；STS 在请求时已响应。

• degraded：服务器正常运行，但缺少凭据或 STS 不可访问。

• error：安全配置或内部注册表无法初始化。

身份会被匿名化：只保留主体的通用类型，以及（如果存在）一个掩码账户。不执行清单、Resource Explorer、适配器、CloudTrail 或 CloudWatch。

listar_recursos_aws

查询本地凭据可用的 AWS 清单，不修改任何资源。参数：

• region：将搜索限制在某个区域；无值时使用所有可用覆盖范围。

• services：按服务过滤，例如 lambda、s3、ec2 或 rds。

• include_account_id：允许从响应中省略账户 ID，以便于匿名化。

• resource_types：按动态类型过滤，例如 ec2:instance。

• query：按文本或名称搜索。

• all_regions：当未指定 region 时，使用已启用的区域。

• include_details：在 details 中包含特定元数据。

• include_cost_indicators：包含潜在的成本信号，但不断言实际支出。

• confirm_potentially_billable_operations：已弃用的参数，不再授予任何权限。

• include_activity_summary：仅使用已获取的字段添加简短摘要；不查询 CloudTrail 或 CloudWatch。

• consent_request_id、consent_action 和 approved_services：恢复或取消一个临时且受限的请求。

• timeout_seconds：可配置的预算，范围在 1 到 120 秒之间。

MCP 客户端发送的参数示例：

{
  "region": "eu-west-1",
  "services": ["lambda", "s3"],
  "include_account_id": false,
  "all_regions": true
}

第一次调用返回通过允许的操作获取的资源。如果完成 S3、SQS 或 SNS 需要计费操作，则返回 partial_pending_consent、pending_operations 以及一个五分钟后过期的请求。在第二次显式调用之前，不会执行这些操作：

{
  "consent_request_id": "<id devuelto por la primera llamada>",
  "consent_action": "approve",
  "approved_services": ["s3"]
}

批准是一次性的，与原始身份和范围绑定，并限制操作、区域和请求。发现和丰富化分别授权；额外的页面需要新的请求。consent_action: "cancel" 不执行 AWS 清单。

状态区分 complete_for_requested_scope、partial_pending_consent、partial_timeout、partial_permission_denied、partial_unavailable、consent_cancelled 和 error。空列表仅表示该服务在被查询时是空的。

resources、all_resources 和 resources_by_service 表示相同的去重清单。每个资源包含 id、arn、name、service、resource_type、region、account_id、state、created_at、sources、details、cost_indicators 和 activity。该工具不计算成本、不查询 Free Tier，也不执行写入操作。

analizar_actividad_recursos

通过相同的注册表和模型分析所有资源的最后已知迹象。接受按 services、regions 和 resource_ids 过滤，以及 inactive_days、lookback_days、include_administrative_events 和可配置的限制。CloudTrail 历史记录限制为 90 天，并按区域查询，而不是按资源查询。

响应区分 last_functional_usage_at、last_administrative_activity_at、last_configuration_change_at 和 last_state_change_at。best_known_activity_at 始终同时指示信号类型。活动状态、Describe* 查询或修改日期不会被呈现为功能使用。

每个资源的状态为 active、inactive_candidate、unknown、not_supported 或 error。不活动候选仅是一个需要审查的项目：它需要足够的时间、已查询的相关来源以及没有矛盾的近期证据。权限不足、来源不充分或关系不明确会产生 unknown，而不是虚假的不活动确定性。

CloudWatch 可能提供功能指标，但 GetMetricData、GetMetricStatistics 和 ListMetrics 被注册为可能计费并被阻止。include_paid_sources=true 仅请求结构化说明；它不构成同意，并且在此阶段绝不执行这些操作。

diagnosticar_cobertura_aws

解释 MCP 实际可以查询什么，而不枚举资源。接受 services 和 regions 过滤器，并允许省略权限、活动或经济策略部分。

检查 STS、已启用的区域、Resource Explorer 的现有索引、适配器的注册表和能力、免费的活动来源以及被阻止的操作。每次执行的检查限制为五个区域、一个 CloudTrail 样本，并且不进行任何 CloudWatch 调用。

覆盖状态区分 available、partial、unavailable、not_configured、permission_denied、blocked_by_cost_policy、not_supported、not_checked 和 error。策略中声明为允许的操作不会被呈现为已证明的 IAM 权限：诊断不会执行服务清单来验证它。

示例：

{
  "services": ["ec2", "rds"],
  "regions": ["eu-west-1"],
  "include_activity_sources": true
}

限制会指示影响、MCP 是否可以继续、是否缺少权限、解决它们是否需要写入操作以及是否可能产生成本。诊断从不执行建议的操作。

analizar_riesgo_costes

通过清单指标以及（可选）通用活动管道对资源进行优先级排序。返回 none_detected、low、medium、high、critical 或 unknown、可解释的评分以及不可执行的建议。信号不确认支出，none_detected 也不意味着零成本。

include_free_tier=true 添加 Free Tier 的官方数据。include_actual_cost=true 仅准备 Cost Explorer 的同意：不执行查询。

revisar_free_tier

查询 GetFreeTierUsage 和 GetAccountPlanState，这些是 AWS 文档中记录为免费的操作。区分月度限制、预测、计划和积分。可能因权限、更新延迟、优惠耗尽或资格差异而返回部分或未知信息。不声称任何特定资源是免费的。

consultar_costes_aws

为精确的时期和过滤器准备聚合的 GetCostAndUsage 查询。第一次调用执行零个 AWS 操作，并返回一个临时请求，其中包含主视图上每次请求 0.01 USD 的已发布价格。使用 consent_action="approve" 的第二次调用最多执行一页；每个额外的页面都需要新的同意。cancel 不调用 AWS。

粒度可以是 MONTHLY 或 DAILY；end_date 是排他性的。预测、按资源的详细信息、关联账户和自定义账单视图在此阶段未实现。

AWS 清单

Boto3 是 AWS 官方的 Python SDK。清单层使用：

• STS GetCallerIdentity 用于识别账户和有效身份。

• EC2 DescribeRegions 仅用于发现已启用的区域。

• Resource Explorer 通过现有索引和视图动态发现资源和受支持的类型。

• 一个通用的适配器注册表，用于 Lambda、S3、EC2/EBS/VPC、RDS/Aurora、DynamoDB、ECS/Fargate、API Gateway、CloudFormation、SQS、SNS、IAM、CloudFront 和 Route 53。

• CloudTrail LookupEvents 用于过去 90 天的免费区域管理事件历史记录。

Lambda 和 S3 是最早实现的服务，但不再保留特殊的架构路径。所有适配器都通过相同的契约声明元数据、Boto3 操作、范围、类型、详细信息和指标。特定细节仅存在于 details 中。

结果按 ARN 去重，如果缺少 ARN，则按类型、区域和标识符/名称去重。优先使用聚合索引；使用本地索引时，结果会被合并，覆盖范围是部分的。如果 Resource Explorer 不可用，则运行所有支持发现且已选择的适配器。

缺少凭据或无法识别账户，对清单来说是全局错误，但对本地健康来说只是 degraded 状态。诊断保留其本地检查，并安全地跳过依赖 AWS 的检查。

所有 Boto3 调用首先经过中央注册表。未注册、写入或成本未知的操作会被阻止。free-only 模式在整个过程中保持激活。S3、SQS 和 SNS 可以计入请求：它们的枚举显示为待处理，只有精确的临时 grant 才能执行它们。守卫分别统计唯一操作和实际请求。

MCP 客户端的示例：“我的账户中有哪些资源？”、“列出 eu-west-1 的 EC2 实例”、“搜索名为 web 的资源”或“显示已部署的 RDS 类型”。Resource Explorer 提供广泛而非全面的覆盖。

文档

• 架构

• 决策

• 阶段

• 进度

• 零成本策略

• 服务适配器

• 活动分析

• 诊断与覆盖

• 清单同意流程

• 经济分析、Free Tier 与实际成本

• 最小权限 IAM

• IAM 权限矩阵

• 手动 IAM 配置