AWS Resource MCP
This server is a local, read-only MCP tool that answers natural-language questions about AWS inventory, activity, coverage, Free Tier, and cost risk.
Run a health check with optional guarded AWS identity verification.
Inventory AWS resources (normalized, deduplicated) with optional region, service, and cost-indicator filters.
Analyze resource activity using free API fields and CloudTrail management events, separating usage from configuration changes.
Diagnose AWS coverage: reachable services, regions, permissions, Resource Explorer indexes, activity sources, and cost policy.
Assess cost risk using configuration-based indicators without claiming actual spend.
Review Free Tier usage and account plan state via official no-cost APIs.
Prepare and, only after explicit single-use consent, execute one bounded Cost Explorer query.
Enforce read-only operations, fail-closed behavior, budgets, and explicit partial-result reporting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AWS Resource MCP list my Lambda functions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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(), andconsultar_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 syncRun the server
uv run aws-resource-mcpFor diagnostics it can also be run as a module:
uv run python -m aws_resource_mcp.serverThe 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.pyRun the tests
uv run pytestGenerate and validate IAM policies
uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --checkGeneration 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-identityThen run the inventory in the default region eu-west-1:
uv run python -m aws_resource_mcp.aws.inventoryThe region and shared profile are optional:
uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile exampleNo 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 aslambda,s3,ec2, orrds.include_account_id: allows omitting the account ID from the response to make it easier to anonymize.resource_types: filters by dynamic types such asec2:instance.query: searches by text or name.all_regions: uses enabled regions whenregionis not specified.include_details: includes service-specific metadata insidedetails.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, andapproved_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
GetCallerIdentityto identify the account and effective identity.EC2
DescribeRegionsto 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
LookupEventsfor 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 toolsanalizar_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for creating and managing AWS resources using boto3, including EC2, S3, VPC, subnets, security groups, and RDS.MIT
- FlicenseNot gradedqualityDmaintenanceA 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.-
- FlicenseNot gradedqualityDmaintenanceThis MCP server provides tools for inspecting AWS cloud infrastructure, including listing S3 buckets, EC2 instances, and fetching CloudWatch logs using your local AWS credentials.-
- AlicenseAqualityDmaintenanceA Python MCP server that lets MCP-compatible clients inspect and operate AWS through the AWS CLI, with command execution, suggestions, region lookup, and caller identity checks.4MIT