mcp-aws

A read-only AWS MCP server for stdio, designed to sit behind an MCP gateway.

The problem it solves

One tool per AWS API operation gives you hundreds of tools. Every tool schema is resent to the model on every turn, so a broad AWS server spends the context budget before the first question is asked.

mcp-aws registers five tools, permanently, over a catalog of read-only views declared in YAML. Coverage grows by adding YAML; the tool surface does not move. The catalog is discovered at runtime, so a model pays for the one view it needs instead of carrying the whole of AWS.

aws_list_accounts    which profiles (accounts) are configured and usable
aws_catalog          view ids + one-line summaries, filterable by service or search
aws_describe_view    one view's parameters and output shape, on demand
aws_query            run a view against a profile and region
aws_read_resource    ARN in, the matching detail view out

Typical flow: aws_catalog(service="eks") → aws_describe_view("eks.nodegroups.list") → aws_query(...).

Related MCP server: AWS Security MCP Server

Install and run

uv sync
uv run mcp-aws          # speaks MCP over stdio

Gateway / client config:

{
  "mcpServers": {
    "aws": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-aws", "mcp-aws"],
      "env": { "AWS_CONFIG_FILE": "/Users/you/.aws/config" }
    }
  }
}

Credentials

Each named profile in your AWS config is treated as an account. Nothing is assumed or assume-roled on your behalf. aws_list_accounts resolves every profile concurrently and reports per-profile status, so one expired SSO session degrades that row rather than the call:

{"profile": "prod", "account_id": "123456789012", "account_alias": "acme-prod",
 "default_region": "us-east-1", "status": "ok"}

Read-only by construction

Read-only is enforced at catalog load, not at call time:

1. The operation name must match a read-only prefix (describe_, list_, get_, …).

2. The operation must exist in the botocore service model, and every declared parameter must be a real member of its request shape.

3. Read-shaped but sensitive operations (s3:get_object, secretsmanager:get_secret_value, ssm:get_parameter, kms:decrypt, log and item reads …) are denylisted outright.

A view that fails any of these aborts startup. The engine can only ever invoke an operation that survived, so there is no code path from a tool call to a mutating API.

Adding coverage

Add an entry to a file in src/mcp_aws/catalog/views/. No Python, no new tool, no change to the context cost:

- id: ec2.vpcs.list
  summary: VPCs with CIDR blocks and default flag
  client: ec2                 # boto3 client name
  operation: describe_vpcs    # snake_case, must be read-only and real
  paginate: true
  params:
    vpc_ids:
      type: "string[]"
      description: Specific VPC ids.
      maps_to: VpcIds         # request member, 'A.B' nesting, or 'Filters[vpc-id]'
  project: |                  # JMESPath, applied per page
    Vpcs[].{id: VpcId, cidr: CidrBlock, is_default: IsDefault}
  returns: One object per VPC.
  detail_of: ec2:vpc          # optional: makes this the target of aws_read_resource
  detail_param: vpc_ids

uv run pytest tests/test_catalog.py validates every view against the real AWS models.

Two constructs cover the awkward APIs:

• expand — a declarative fan-out for services that split a list from its detail (eks:list_clusters + describe_cluster). inherit carries the parent's key into the child call, for describe_nodegroup and friends that need clusterName too. Bounded by max_items and a small thread pool.

• Filters[$param] — a filter whose key is user data rather than part of the API contract, as the Resource Groups Tagging API needs. $self means this parameter's own value is the key; $other takes the key from a sibling parameter.

Point MCP_AWS_CATALOG_DIR at your own directory to add or override views without forking the package.

Results and pagination

Every response uses one envelope:

{"view": "ec2.instances.list", "profile": "prod", "region": "us-east-1",
 "count": 100, "truncated": true, "next_cursor": "eyJ0Ijo…", "items": [...]}

Results are capped by item count and serialized size. Truncation is lossless: each item records the page it came from, so a cut landing in the middle of an AWS page still produces a cursor that resumes at exactly the first dropped item.

Resources

Tools are the path a model uses; resources are for humans and for clients that browse, @-mention, or build a picker out of them.

Each listing is a JSON Schema enum fragment naming the template one of its values buys, which is what an MCP gateway needs to turn a set into clickable values. Listings are read whenever a client opens the server, so they never call AWS.

aws://query/... pairs with no listing on purpose: a listing beside it would be read on open, and reading it would mean running queries nobody asked for.

Breaking change in this release: the result template was aws://{profile}/{region}/{view_id}. Its fixed prefix was aws://, which shadowed every other URI. It is now aws://query/{profile}/{region}/{view_id}, and aws://catalog returns a vocabulary rather than a full dump — the dump is aws_catalog and aws://catalog/{view_id}.

Behind a gateway

Everything in this section is ordinary MCP; a client that ignores it loses nothing.

• Injectable values. The listing/template pairs above publish the four argument names worth picking rather than typing — profile, region, view_id and service. A gateway's admin UI renders each as chips that fill the matching field.

• Completions. completion/complete answers for those same four, filtered by what has been typed and narrowed by the sibling fields already filled: a view_id asked for beside a chosen service offers only that service's views.

• Prompts. aws_account_overview(profile, region) and aws_investigate_resource(arn, profile). Their argument names are the vocabulary's variables, which is what lets the same chips fill them.

None of this touches the tool surface: resources, templates, completions and prompts are fetched on demand instead of being resent every turn.

Configuration

Coverage today

Twenty-six views across seven services. The prefix is a grouping label, not the AWS client — account.regions calls ec2, and resources is not an AWS service at all.

• account — identity, regions

• resources — tagged-resource inventory across services, tag keys, tag values

• org — accounts, roots, OUs

• ec2 — instances, security groups, VPCs, subnets, route tables, volumes, NAT gateways

• elbv2 — load balancers, target groups, listeners, target health

• autoscaling — groups

• eks — clusters, node groups, add-ons, Fargate profiles

Development

uv run pytest          # no network, no credentials; AWS is stubbed