One server, one config entry, and the whole AWS API behind it - generic CRUD over hundreds of resource types, multi-region fan-out, and SSO re-login that does not drop you back to a terminal.
@yawlabs/aws-mcp is a small AWS MCP for AI assistants: one server, one config entry, SSO re-auth baked in, generic CRUD over hundreds of resource types, live docs lookup, and server-side scripting for batched workflows. Built and maintained by Yaw Labs, MIT licensed, published on npm.
npx -y @yawlabs/aws-mcp@latestGitHub · npm · Add to Yaw MCP
Anyone who works AWS from a terminal and would rather describe the outcome than assemble the calls. This is an alternative to AWS's official MCP server, not a complement - both call any AWS API, so running both just gives the model two redundant tools. Pick one. What this one is good at:
The one thing that pairs cleanly with either choice is AWS Labs' fleet of typed per-service servers (awslabs/mcp) - Lambda invoke, Bedrock retrieval, DynamoDB with type marshalling. Those are per-service helpers with no tool-name overlap with a general AWS-API server.
1. Have the AWS CLI and a profile ready. You need AWS CLI v2 on your PATH - the server shells out to it, including for aws sso login - and a profile configured for SSO or IAM Identity Center in ~/.aws/config. AWS CLI v1 is unsupported. Newer v2 releases need --use-device-code to keep printing a short code; the server probes aws --version once and adapts, so older v2 installs keep working.
Point the server at the profile and region you normally work in:
| Variable | Default | Purpose |
|---|---|---|
AWS_PROFILE | default | Profile used when a tool call omits profile. If you authenticate via SAML or a custom credential_process, set this to that profile. |
AWS_REGION / AWS_DEFAULT_REGION | us-east-1 | Region used when a tool call omits region. AWS_REGION wins if both are set. |
AWS_SHARED_CREDENTIALS_FILE | ~/.aws/credentials | Where aws_assume_role writes the profile it creates, honored with ~ expansion so the write lands where the CLI later reads. |
2. Add the server to your client. A .mcp.json in your project root:
{
"mcpServers": {
"aws": {
"command": "npx",
"args": ["-y", "@yawlabs/aws-mcp@latest"]
}
}
}The -y flag is what gives you auto-update on each session load: every time your client spawns the server, npx checks the registry and downloads a newer build if there is one. The check fires only on spawn, so tool calls carry no auto-update overhead. To pin instead, install globally and point the config at the installed binary:
npm install -g @yawlabs/aws-mcp
{
"mcpServers": {
"aws": {
"command": "aws-mcp"
}
}
}3. Restart and approve. Restart Claude Code (or your MCP client) and approve the AWS server when prompted. Then ask it something: "Who am I in AWS right now, and how long until my SSO token expires?"
Running Yaw MCP? One click adds it to your local config, and it is then available in every Yaw Terminal session.
| Area | What it covers |
|---|---|
| Identity and SSO | aws_whoami for account, ARN and token expiry countdown; aws_login_start / aws_login_complete for the device-code flow; aws_refresh_if_expiring_soon for a proactive top-up |
| Sessions and profiles | Set, read and clear the session profile and region, list the profiles in ~/.aws/config with their SSO metadata, and assume a role into a new named profile for cross-account work |
| Any AWS API | aws_call proxies the aws CLI directly, so the full API surface - including services AWS adds tomorrow - is reachable the moment your local CLI knows them. aws_paginate walks paginated list and describe operations, and a JMESPath query parameter trims responses server-side |
| Generic CRUD | The aws_resource_* family wraps Cloud Control API, so get / list / create / update / delete / status works for any control-plane resource with a CloudFormation schema. awaitCompletion polls an async operation through to terminal state in one call |
| Dry runs | aws_resource_diff fetches current state, simulates the RFC 6902 patch in memory, and returns before, after and a per-op change list. No mutation is sent to AWS |
| Observability | CloudWatch Logs tailing with filters and a bounded event budget, Logs Insights queries run start-to-rows in one call, and GetMetricData queries with relative time shorthand and auto-picked periods |
| IAM pre-flight | aws_iam_simulate answers "can this principal do these actions on these resources" before you try, returning the decision, the statements that decided it, and any context keys the policy wanted |
| Lambda | aws_lambda_invoke returns the response payload plus the decoded execution log tail - the one Lambda path a generic CLI proxy structurally cannot do, because aws lambda invoke takes the body as a required positional outfile |
| Fan-out | aws_multi_region and aws_multi_account run the same operation in parallel across regions or accounts, returning a per-entry result with success and error counts computed before any response capping |
| Scripting | aws_script runs a short JS snippet that orchestrates the other tools and returns one combined result - read the trust note below before using it |
| Live docs | aws_docs_search queries the backend behind the docs.aws.amazon.com search box and aws_docs_read returns a doc page as paginated markdown, so the model can look up exact parameter names without a second MCP server |
readOnlyHint, destructiveHint, idempotentHint and openWorldHint tell an MCP host how to gate a call. The guarantee has a direction: an annotation may be tightened in a patch release when it was understating what a tool can do, and will not be loosened outside a major.aws_call and aws_multi_region as able to invoke any AWS API the caller's IAM identity permits, deletes included. They are marked destructive for exactly that reason.aws_script is not a security boundary. The script runs in this server's own process and host globals remain reachable from inside it, so it is strictly more powerful than the other tools - those are bounded by AWS and your IAM policy, this one is not. Only pass script text you would run on this machine yourself, never text that arrived from a log line, a resource tag, or any other AWS response.aws_assume_role stashes the temporary credentials as a profile on disk and returns the profile name, not the secret or session token. aws_multi_account holds each account's credentials in memory for the life of the call and writes nothing to ~/.aws/credentials, so a sweep that dies midway does not leave live keys behind.aws_iam_simulate is meant to be called before a risky operation, and it distinguishes an explicit deny from an implicit one and names the statements that decided.errorKind rides alongside the human-readable message, and the three credential kinds are deliberately distinct because the remedy differs: none found, resolved but rejected, or a temporary session that expired. Anchor automation on that field rather than regex-matching the message text, which is explicitly best-effort.AWS_ACCESS_KEY_ID and friends exported in your shell are never consulted. Put static keys in a profile section of ~/.aws/credentials instead. Container credentials and IMDS sit later in the chain and are unaffected.This is the part that justifies a local server. When aws sso login tries to open a browser from a subprocess, the handoff drops silently on Windows and sometimes elsewhere - you end up switching to a terminal, running the command yourself, then coming back. The device-code flow removes that:
1. The agent calls aws_login_start({ profile: "prod" })
2. Server spawns: aws sso login --no-browser --use-device-code --profile prod
3. Server parses the verification URL and short code out of stdout
4. The agent surfaces: open https://device.sso.<region>.amazonaws.com/ and enter ABCD-EFGH
5. You click - the browser opens in your own user session - auth in seconds
6. The agent calls aws_login_complete({ sessionId }) and gets your new identityThe token lands in ~/.aws/sso/cache/ the same way a normal login would cache it, so the AWS CLI, the SDK and every other tool on your machine pick it up transparently. That cache also explains why this server is stdio and local rather than hosted: SSO tokens live on your device, and a remote MCP server cannot read them. That is a constraint of AWS SSO, not of hosting.
It puts the AWS CLI's full API surface behind MCP tools, so an agent can run any AWS operation, page through a long list, fan the same call out across regions or accounts, and do generic create, read, update and delete against any control-plane resource with a CloudFormation schema through Cloud Control API. Live AWS documentation search and page reads are built in, so the model can look up an exact parameter name without a second server installed.
They are an either/or rather than a pair: both call any AWS API, so running both just gives the model two redundant tools. AWS's server is hosted, needs Python and uv, and brings AWS-team-curated skills, a server-side Python sandbox and days-fresh API coverage. This one is Node and npm only, runs locally, and wins on SSO re-login when the browser handoff drops, Cloud Control CRUD with dry-run diffs, multi-region fan-out, IAM pre-flight checks and a JS scripting tool for batching. AWS Labs' per-service servers are a different thing again and pair cleanly with whichever you pick.
The server runs the device-code flow for you. aws_login_start spawns aws sso login with the no-browser device-code options, parses the verification URL and short code out of the CLI, and hands them back for the agent to surface; you click once, authenticate, and aws_login_complete returns your new identity. The token is cached in ~/.aws/sso/cache exactly as a normal aws sso login would cache it, so the AWS CLI, the SDK and every other tool on your machine pick it up transparently. aws_refresh_if_expiring_soon does the same check proactively before a long workflow.
No, and the README says so plainly: the script runs in this server's own process, host globals remain reachable from inside it, and it is strictly more powerful than the other tools, which are bounded by AWS and your IAM policy. require, import, process, fs, fetch and timers are not bound into the context, but that is ergonomics rather than a security boundary. Only pass script text you would run on this machine yourself - never text that arrived from a log line, a resource tag, or any other AWS response.
The boundary here is IAM rather than a server-side toggle. Every tool is annotated with readOnlyHint, destructiveHint, idempotentHint and openWorldHint so your client can gate calls, and aws_call, aws_multi_region and aws_resource_update are all marked destructive precisely because they can invoke any AWS API the caller's identity permits, including deletes. Point AWS_PROFILE at a profile whose role grants only what you want the agent to reach, and use aws_iam_simulate to check a permission before attempting the operation rather than after the 403.
Published by Yaw Labs.