Skip to main content
Glama
AWS Resource MCP

AWS Resource MCP

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: Lambda 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

Available Tools

7 tools
analizar_actividad_recursosA

Analyze last known AWS resource activity with conservative semantics.

Free service API fields and CloudTrail Event History management events are
combined through the common adapter pipeline. Functional usage,
administrative activity, configuration changes, and state signals remain
separate. Event History is regional, limited to 90 days, and does not
normally include data events such as S3 GetObject, so unknown results are
expected. CloudWatch could improve functional-usage coverage but is always
blocked in this phase: setting ``include_paid_sources`` only requests a
structured explanation and never grants consent or executes a metric call.
The operation is read-only, bounded, and may return partial results.

Inputs: regions, services, max_regions, resource_ids, +7 more. Returns: object

analizar_riesgo_costesA

Prioritize potential AWS cost risk without treating it as actual spend.

The analysis uses the common inventory model and its cost indicators.
Optional activity is merged through the existing uniform activity tool.
Free Tier data uses the officially free API. ``include_actual_cost=True``
only prepares a separate Cost Explorer consent request; it does not grant
consent or execute a potentially billable operation. Recommendations are
informational and no AWS resource is changed.

Inputs: regions, services, period_days, resource_ids, +4 more. Returns: object

consultar_costes_awsA

Prepare or execute one exact, potentially billable Cost Explorer query.

The first call performs no AWS operation. It returns an expiring,
single-use request that states the exact period, filters, operation,
maximum request count, and estimated API charge. Calling again with the
request id and ``consent_action="approve"`` executes at most one
GetCostAndUsage page. A continuation page always needs a new consent.
``cancel`` performs no AWS call. Approval never authorizes another
operation, period, filter, identity, forecast, or resource-level query.

Inputs: regions, end_date, services, max_pages, +8 more. Returns: object

diagnosticar_cobertura_awsA

Explain which AWS coverage is reachable and why it may be partial.

This read-only diagnostic checks STS, enabled Regions, existing Resource Explorer indexes, the shared adapter registry, free activity sources, and the central cost policy. It does not inventory resources, create indexes, change IAM, enable Regions, or run CloudWatch. Adapter permissions are reported conservatively because service inventory calls are not executed. Results may be partial and never prove that an unqueried service is empty.

Inputs: regions, services, include_cost_policy, include_permissions, +1 more. Returns: object

health_checkA

Check local server health and optionally perform one guarded STS call.

The AWS check never runs inventory, adapters, Resource Explorer, CloudTrail, CloudWatch, or any regional scan. Missing credentials degrade AWS access but do not mean the local MCP server is down.

Inputs: check_aws. Returns: object

listar_recursos_awsA

Discover AWS resources through locally available credentials, read-only.

Runs free read-only discovery first. Operations that AWS can meter as
requests are returned as pending and are not executed. To continue, call
this same tool with the short-lived ``consent_request_id``,
``consent_action="approve"``, and an explicit subset in
``approved_services``. Approval is single-use, identity- and scope-bound,
request-limited, and does not authorize enrichment or extra pagination.
``consent_action="cancel"`` performs no AWS inventory call. The legacy
``confirm_potentially_billable_operations`` flag is retained for signature
compatibility but grants no permission.

Every service uses the same adapter pipeline and normalized resource model.
Coverage can be partial because of pending consent, timeout, permissions,
unavailable APIs, or Resource Explorer configuration. An empty result is
therefore distinct from a service that was not queried. This tool never
writes resources, lists S3 objects, reads queue messages, publishes topics,
calculates actual costs, or guarantees that a metered request is free.

Inputs: query, region, services, all_regions, +10 more. Returns: object

revisar_free_tierA

Review account-plan and Free Tier usage without querying billed costs.

AWS officially documents programmatic Free Tier usage and account-plan monitoring at no cost. This read-only tool uses only GetFreeTierUsage and GetAccountPlanState. It does not call Cost Explorer, prove that a resource is free, or guarantee future eligibility. Usage can be estimated, delayed, absent after a limit is exhausted, or unavailable because of IAM.

Inputs: services, max_pages, include_forecast. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: health check, coverage diagnosis, resource listing, activity analysis, cost risk, free tier, and cost queries. No two tools overlap in functionality.

    Naming Consistency4/5

    All names use snake_case and are descriptive, but there is an inconsistency in language: one tool is in English (health_check) while the rest are in Spanish. This is a minor deviation from a consistent pattern.

    Tool Count5/5

    Seven tools is a well-scoped set for a server focused on AWS resource discovery and cost analysis. Each tool covers a distinct aspect without being too few or too many.

    Completeness4/5

    The tool surface covers the main areas of health, coverage, resource discovery, activity, and cost (including free tier and actual cost). Minor gaps like direct resource detail queries are addressed by the generic listing tool, so overall completeness is high.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A stateless Python MCP server packaged as a custom AWS Lambda container image, exposing basic tools like hello, add, and current_time through an API Gateway HTTP API.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      This MCP server provides tools for inspecting AWS cloud infrastructure, including listing S3 buckets, EC2 instances, and fetching CloudWatch logs using your local AWS credentials.
      -