AWS Resource MCP

Local MCP server, developed in Python, for querying real resources from an AWS account in read-only mode.

Status

Phase 9 is implemented. The server combines uniform inventory, conservative activity analysis, explicit diagnostics, economic analysis, and least-privilege IAM policies generated from the actual operations log.

Related MCP server: aws-mcp-server

Planned scope

• Local MCP transport via stdio.

• Primary region: eu-west-1.

• AWS queries exclusively read-only and least-privilege.

• Available tools: health_check(), listar_recursos_aws(), analizar_actividad_recursos(), diagnosticar_cobertura_aws(), analizar_riesgo_costes(), revisar_free_tier(), and consultar_costes_aws().

• Cost Explorer is blocked until ephemeral consent is received for an exact request.

• No deployment on AWS or CD.

Reliability

Phase 10 incorporates local integration, contract, security, performance, and MCP protocol tests. The inventory also applies AWS_MCP_MAX_REQUESTS_PER_TOOL (250 by default) before each SDK call; when exhausted, it preserves the result and returns partial_request_budget_exhausted.

Continuous integration runs formatting, linting, compilation, deterministic IAM validation, and local tests on every pull request. It does not configure AWS credentials or run AWS operations.

Using with Codex

Codex is the primary client. Use the package entry point uv run aws-resource-mcp over stdio, configure any AWS profile outside the repository, and begin with natural-language questions such as "What resources do I have in eu-west-1?". When a response is partial_pending_consent, Codex must explain the exact operation and wait for explicit approval; it never creates persistent consent. See Codex integration and the demo.

Release v0.1.0

The first version is ready for review: it includes the read-only guard, ephemeral consent, Codex integration, and CI. See the release checklist to verify it locally and run the safe demo.

Development

The project is managed with uv and Python 3.12 or later.

Install dependencies

uv sync

Run the server

uv run aws-resource-mcp

For diagnostics it can also be run as a module:

uv run python -m aws_resource_mcp.server

The server uses stdio: it expects an MCP client to exchange messages over standard input and output. It can be opened with MCP Inspector using the tools included in the SDK:

uv run mcp dev src/aws_resource_mcp/server.py

Run the tests

uv run pytest

Generate and validate IAM policies

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

Generation is local, deterministic, and uses no credentials. The project does not create or modify roles or policies in AWS. The policies separate free operations, reads that require consent, and the combined maximum; IAM permission never replaces application consent.

Run the AWS inventory

Before the real diagnostic, check which identity the local configuration will resolve:

aws sts get-caller-identity

Then run the inventory in the default region eu-west-1:

uv run python -m aws_resource_mcp.aws.inventory

The region and shared profile are optional:

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

No keys are stored in the project. Boto3 uses its standard credential resolution chain; if AWS_PROFILE or --profile is specified, it only selects a profile that must already exist outside the repository.

MCP Tools

health_check

health_check(check_aws=True) separates local health from AWS accessibility. Without arguments it makes at most one protected STS call; with check_aws=false it uses no network. It returns version, transport, tools, and registered adapters, region, cost policy, and zero billable operations. Its states are:

• ok: server and configuration valid; STS responded when requested.

• degraded: the server works, but credentials are missing or STS is not accessible.

• error: the secure configuration or internal registries cannot be initialized.

Identity is anonymized: only the general principal type and, when present, a masked account are kept. It does not run inventory, Resource Explorer, adapters, CloudTrail, or CloudWatch.

listar_recursos_aws

Queries the AWS inventory available to the local credentials without modifying resources. Parameters:

• region: limits the search to one region; without a value it uses all available coverage.

• services: filters by services such as lambda, s3, ec2, or rds.

• include_account_id: allows omitting the account ID from the response to make it easier to anonymize.

• resource_types: filters by dynamic types such as ec2:instance.

• query: searches by text or name.

• all_regions: uses enabled regions when region is not specified.

• include_details: includes service-specific metadata inside details.

• include_cost_indicators: includes potential cost signals without asserting actual spend.

• confirm_potentially_billable_operations: legacy parameter that no longer grants permissions.

• include_activity_summary: adds a brief summary using only fields already obtained; it does not query CloudTrail or CloudWatch.

• consent_request_id, consent_action, and approved_services: resume or cancel an ephemeral, scoped request.

• timeout_seconds: configurable budget between 1 and 120 seconds.

Example of arguments sent by an MCP client:

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

The first call returns the resources obtained through allowed operations. If completing S3, SQS, or SNS requires billable operations, it returns partial_pending_consent, pending_operations, and a request that expires in five minutes. It does not run those operations until an explicit second call:

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

Approval is single-use, tied to the original identity and scope, and limits operations, regions, and requests. Discovery and enrichment are authorized separately; an additional page requires a new request. consent_action: "cancel" does not run the AWS inventory.

The states distinguish complete_for_requested_scope, partial_pending_consent, partial_timeout, partial_permission_denied, partial_unavailable, consent_cancelled, and error. An empty list only means the service was empty when queried.

resources, all_resources, and resources_by_service represent the same deduplicated inventory. Each resource contains id, arn, name, service, resource_type, region, account_id, state, created_at, sources, details, cost_indicators, and activity. The tool does not calculate costs, does not query Free Tier, and does not perform write operations.

analizar_actividad_recursos

Analyzes the last known signal using the same log and model for all resources. It accepts filters by services, regions, and resource_ids, plus inactive_days, lookback_days, include_administrative_events, and configurable limits. The CloudTrail history is limited to 90 days and is queried per region, not once per resource.

The response separates last_functional_usage_at, last_administrative_activity_at, last_configuration_change_at, and last_state_change_at. best_known_activity_at always also indicates the signal type. An active state, a Describe* call, or a modification date is not presented as functional usage.

Per-resource states are active, inactive_candidate, unknown, not_supported, or error. An inactive candidate is only an item for review: it requires sufficient age, a relevant source queried, and no recent contradictory evidence. Missing permissions, insufficient sources, or ambiguous relationships produce unknown, not a false certainty of inactivity.

CloudWatch could provide functional metrics, but GetMetricData, GetMetricStatistics, and ListMetrics are registered as potentially billable and blocked. include_paid_sources=true only requests the structured explanation; it does not constitute consent and never runs those operations in this phase.

diagnosticar_cobertura_aws

Explains what the MCP can actually query without enumerating resources. It accepts services and regions filters and allows omitting the permissions, activity, or cost policy sections.

It checks STS, enabled regions, existing Resource Explorer indexes, adapter registration and capabilities, free activity sources, and blocked operations. Checks are limited to five regions per run, one CloudTrail sample, and no CloudWatch calls.

Coverage states distinguish available, partial, unavailable, not_configured, permission_denied, blocked_by_cost_policy, not_supported, not_checked, and error. An operation declared as allowed by the policy is not presented as proven IAM permission: the diagnostic does not run service inventories to test it.

Example:

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

Limitations indicate impact, whether the MCP can continue, whether permissions are missing, whether resolving them would require writes, and whether cost could exist. The diagnostic never performs the suggested action.

analizar_riesgo_costes

Prioritizes resources using inventory indicators and, optionally, the common activity pipeline. It returns none_detected, low, medium, high, critical, or unknown, an explainable score, and non-executable recommendations. A signal does not confirm spend, and none_detected does not mean zero cost.

include_free_tier=true adds official Free Tier data. include_actual_cost=true only prepares a Cost Explorer consent: it does not perform the query.

revisar_free_tier

Queries GetFreeTierUsage and GetAccountPlanState, operations AWS documents as free. It separates monthly limits, forecast, plan, and credits. It may return partial or unknown information due to permissions, update lag, an exhausted offer, or eligibility differences. It does not claim that a specific resource is free.

consultar_costes_aws

Prepares an aggregated GetCostAndUsage query for an exact period and filters. The first call runs zero AWS operations and returns an ephemeral request with the published price of 0.01 USD per request on the primary view. A second call with consent_action="approve" runs at most one page; each additional page requires new consent. cancel does not call AWS.

Granularity can be MONTHLY or DAILY; end_date is exclusive. Forecast, per-resource detail, linked accounts, and custom billing views are not implemented in this phase.

AWS Inventory

Boto3 is the official AWS SDK for Python. The inventory layer uses:

• STS GetCallerIdentity to identify the account and effective identity.

• EC2 DescribeRegions to discover only enabled regions.

• Resource Explorer to dynamically discover resources and supported types through existing indexes and views.

• A common adapter registry for Lambda, S3, EC2/EBS/VPC, RDS/Aurora, DynamoDB, ECS/Fargate, API Gateway, CloudFormation, SQS, SNS, IAM, CloudFront, and Route 53.

• CloudTrail LookupEvents for the free regional management event history of the last 90 days.

Lambda and S3 were the first implemented services, but they no longer keep special architectural paths. All adapters declare metadata, Boto3 operations, scope, types, details, and indicators through the same contract. Service-specific details live only inside details.

Results are deduplicated by ARN or, if missing, by type, region, and identifier/name. An aggregator index is preferred; with local indexes, results are combined and coverage is partial. If Resource Explorer is unavailable, all selected adapters that support discovery are run.

The absence of credentials or the inability to identify the account is a global error for inventory, but only a degraded state for local health. The diagnosis preserves its local checks and safely omits AWS-dependent ones.

All Boto3 calls first pass through a central log. Unregistered, write, or unknown-cost operations are blocked. The free-only mode remains active throughout the process. S3, SQS, and SNS can count requests: their enumerations are presented as pending, and only an exact ephemeral grant allows them to be executed. The guard counts unique operations and real requests separately.

Examples for an MCP client: "What resources are in my account?", "List EC2 instances in eu-west-1", "Search for resources named web" or "Show me deployed RDS types". Resource Explorer offers broad, not universal, coverage.

Documentation

• Architecture

• Decisions

• Phases

• Progress

• Zero-cost policy

• Service adapters

• Activity analysis

• Diagnostics and coverage

• Inventory consent flow

• Economic analysis, Free Tier and real costs

• Least-privilege IAM

• IAM permissions matrix

• Manual IAM setup