Server data from the Official MCP Registry
AWS MCP server — call any AWS API from AI assistants, with first-class SSO re-login
About
AWS MCP server — call any AWS API from AI assistants, with first-class SSO re-login
Security Report
The visible code is a local AWS CLI wrapper that runs under the user's own AWS profiles and SSO cache, and its README and launcher show no exfiltration, backdoor, or obfuscation. The main concerns are by design: the server exposes general write and delete access to any AWS API with the user's credentials, and the aws_script tool runs in node:vm, which the README itself says is not a security sandbox. Much of the source is truncated, so input validation and argument handling in the aws CLI invocation could not be fully verified. Supply chain analysis found 1 known vulnerability in dependencies (0 critical, 1 high severity). Package verification found 1 issue.
4 files analyzed · 7 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
What You'll Need
Set these up before or after installing:
Environment variable: AWS_PROFILE
Environment variable: AWS_REGION
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"aws-mcp": {
"command": "npx",
"args": [
"-y",
"@yawlabs/aws-mcp@2.7.2"
],
"env": {
"AWS_REGION": "your-aws-region-here",
"AWS_PROFILE": "your-aws-profile-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
@yawlabs/aws-mcp
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Tested with Yaw MCP 1.1.13 or newer. Or install manually below.
A small AWS MCP for AI assistants: one server, one config entry, SSO re-auth baked in, generic CRUD over 1,300+ resource types, live docs lookup, server-side scripting for batched workflows.
It's an alternative to AWS's official MCP server, not a complement -- both reach any AWS API, so running both hands the model two overlapping ways to do the same thing. (AWS gives the same advice about its own older servers: its setup guide says to remove them "to avoid tool conflicts that can confuse AI agents".) Pick one. They overlap in coverage and differ in shape. The honest comparison:
- AWS MCP Server -- AWS's hosted server, GA since May 2026 and part of the Agent Toolkit for AWS. Strong on AWS-team-curated skills, a server-side Python sandbox (
run_script) with days-fresh API coverage, a read-only serverless troubleshooting capability (Lambdadiagnose, recent changes, X-Ray trace summaries), IAM condition keys that tell its calls apart from direct API calls, and per-tool CloudWatch metrics. As of September 2026,run_scriptis its only general-purpose way to call an AWS API -- the single-callcall_awstool has been removed -- so every call, even a one-offdescribe, is a Python script the model writes. The endpoint runs inus-east-1andeu-central-1. Two ways to connect:- OAuth through AWS Sign-in (since July 2026): nothing to install -- your client opens a browser and connects straight to the endpoint. Each session is bound to one IAM role and refreshes for up to 12 hours, and the principal needs
signin:AuthorizeOAuth2Accessandsignin:CreateOAuth2Token. - SigV4 through a local proxy run with
uv(uvx mcp-proxy-for-aws-cli@latestin AWS's guide), signing with your AWS CLI credentials (CLI 2.32.0+). AWS recommends this path for terminal and IDE coding agents, and it is the only one that switches profiles per call, from an allowlist fixed when the proxy starts. Since AWS CLI 2.35.0,aws configure agent-toolkitwrites a SigV4 entry (uvx mcp-proxy-for-aws@latest) into your agent's MCP config for you, under the keyaws-mcp.
- OAuth through AWS Sign-in (since July 2026): nothing to install -- your client opens a browser and connects straight to the endpoint. Each session is bound to one IAM role and refreshes for up to 12 hours, and the principal needs
@yawlabs/aws-mcp(this server) -- installs from npm and runs locally on your ownawsCLI and profiles: onenpxline, nouv, no proxy, no hosted hop. Wins on SSO re-login whenaws sso login's browser handoff drops (Windows especially), one AWS operation per tool call (aws_calltakesservice,operationandparams, so a host's approval prompt shows the operation itself, not a script), ergonomic CCAPI CRUD with dry-run diffs, multi-region and multi-account fan-out, pre-flight IAM permission checks, and a JS scripting tool for when you do want a batch (in-process, not a security sandbox -- see the tools table). Live AWS docs search + page read are built in too, so you don't need a second docs server either way -- they cover the same ground as the official server'ssearch_documentation/read_documentation, without its topic routing or skills results.
The MCPs that genuinely pair with either choice are the per-service servers in awslabs/mcp that reach what a general AWS-API tool cannot -- Bedrock's agentic Knowledge Base retrieval is the clearest case (see the companion config). AWS now describes that repo as succeeded by the Agent Toolkit for AWS; it still works and takes contributions, but some of its servers are deprecated or superseded -- its general AWS API server among them -- so check a server's README before adding it.
Five things this server tries to handle well:
- SSO re-login. When your token expires mid-session,
aws sso logintries to open a browser from a subprocess -- on Windows (and sometimes elsewhere) that handoff drops silently. You end up context-switching to a terminal, running the command yourself, then coming back. The--no-browserdevice-code flow fixes this: the assistant surfaces a short URL + code, you click once, done. (--no-browseron its own is no longer enough -- AWS CLI 2.22.0 made the PKCE authorization-code flow the default, and it prints no short code -- so this server pairs it with--use-device-code, probingaws --versiononce to stay compatible with pre-2.22 CLIs.) There's alsoaws_refresh_if_expiring_soonfor proactive top-ups before a long workflow. AWS's hosted server goes around the problem rather than through it. On its OAuth path your MCP client runs its own browser sign-in, and the tokens are bound to that client and that server, so nothing else on the machine benefits; on its SigV4 path, AWS's troubleshooting table tells SSO users to runaws sso loginthemselves and then restart the MCP client. Here the re-login refreshes the same~/.aws/sso/cachetoken the CLI, the SDKs and every other tool on the machine read. - Calling any AWS API.
aws_callproxies theawsCLI directly. One tool covers the full API surface -- including services AWS adds tomorrow -- with no SDK bundling and no service-by-service tool sprawl. That is not aspirational: September 2026's arrivals -- AWS Batch bulkcancel-jobs/terminate-jobs(CLI 2.36.44), the STS session-token size fields (2.36.45), Elastic Beanstalk cluster environments (2.36.47), "Tunnel" VPC endpoints (2.36.48) -- are reachable the moment your localawsCLI knows them, with no@yawlabs/aws-mcpupgrade. An older CLI rejects an operation it does not know before anything is sent, and the error says to upgrade.aws_paginatehandles paginated list/describe ops,aws_multi_regionfans the same op out across N regions in parallel, and a JMESPathqueryparameter trims responses server-side. Reach for them long before this server's 5 MB output cap: MCP hosts cut in much sooner -- Claude Code warns at 10,000 tokens and, by default, saves any result over 25,000 tokens to a file the model has to read back. - Generic CRUD across services.
aws_resource_*(seven tools, includingaws_resource_difffor dry-run previews) wraps AWS Cloud Control API, so the same lifecycle -- get / list / create / update / delete / status -- works for any control-plane resource with a CloudFormation schema: Lambda functions, S3 buckets, IAM roles, SSM parameters, RDS instances, and the rest of the 1,300 types on AWS's published list (not every type implements every verb). PassawaitCompletion: trueand the server polls the async create/update/delete through to terminal state for you. AWS Labs deprecated its own Cloud Control API MCP server in March 2026, and its migration guide lists no direct replacement for resource get / list / create / update / delete: the successor authors CloudFormation and CDK instead. CCAPI is control-plane only. On the data plane, DynamoDBget-item/queryand Bedrockconverseare ordinary operationsaws_callhandles (DynamoDB values stay in its typed JSON,{"S": "..."}), and Lambda invokes have their own tool,aws_lambda_invoke. Three kinds of operation are out ofaws_call's reach: those that write their response body to a positional outfile (S3get-object, Bedrockinvoke-model), the CLI's hand-written commands, which register no--cli-input-json(s3 cp/ls/sync,logs tail,cloudformation deploy), and event-stream operations the CLI does not ship at all (Bedrockconverse-stream,invoke-agent, agentic Knowledge Base retrieval). - Live AWS docs.
aws_docs_searchqueries the same backend that powers the docs.aws.amazon.com search box;aws_docs_readfetches a doc page and returns it as paginated markdown. Lets the agent discover new services and look up exact parameter names without a second MCP server installed. - Batched workflows in one round-trip.
aws_scriptruns a short JS snippet in anode:vmcontext withaws.call,aws.paginate,aws.paginateAll,aws.resource.*,aws.logsTail,aws.metricsQuery,aws.iamSimulate,aws.multiRegion,aws.assumeRole, andaws.docs.{search,read}available. Best for "list X, fetch Y for each, return Z" pipelines that would otherwise need N tool calls. Same idea as AWS'srun_script(Python, sandboxed server-side), which is now that server's only general-purpose way to call an AWS API; here it is the batching option -- JS-native, running locally -- withaws_callfor single operations.
Optional companion: AWS Labs per-service servers
For work a general AWS-API tool cannot do, add the relevant awslabs/mcp server alongside this one. Bedrock's agentic Knowledge Base retrieval is the clearest case: it calls AgenticRetrieveStream, an event-stream operation the AWS CLI leaves out of its command table, so no CLI-based tool -- aws_call included -- can reach it. (Plain retrieval, bedrock-agent-runtime retrieve, is an ordinary aws_call operation.) These are Python servers run with uvx, and they have no tool-name overlap with this one, so they pair cleanly:
{
"mcpServers": {
"aws": {
"command": "npx",
"args": ["-y", "@yawlabs/aws-mcp@latest"]
},
"aws-bedrock-kb": {
"command": "uvx",
"args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
"env": { "AWS_PROFILE": "my-profile", "AWS_REGION": "us-east-1" }
}
}
}
Its agentic tool works on managed knowledge bases, and by default the server lists only knowledge bases tagged mcp-multirag-kb=true; its README covers the tag and the IAM permissions. Skip the older awslabs.lambda-mcp-server: every release is yanked on PyPI, and Lambda invokes are built in here as aws_lambda_invoke.
When to reach for this vs the other AWS MCPs
| Need | Best fit |
|---|---|
Node/npm-only install, running locally on your own aws CLI and profiles (no uv, no proxy) | @yawlabs/aws-mcp |
| Nothing installed locally (remote server, browser sign-in) | AWS MCP Server (OAuth) |
| SSO re-login on Windows / broken browser handoff, fixed for every tool on the machine | @yawlabs/aws-mcp (aws_login_start device-code flow) |
One AWS operation per tool call -- the approval prompt shows service, operation and params, not a script | @yawlabs/aws-mcp (aws_call) |
| Generic CRUD across 1,300+ resource types | @yawlabs/aws-mcp (aws_resource_*) |
| Dry-run an update before applying it | @yawlabs/aws-mcp (aws_resource_diff) |
| Multi-region fan-out in one call | @yawlabs/aws-mcp (aws_multi_region) |
| Same operation across many accounts in one call | @yawlabs/aws-mcp (aws_multi_account) |
| Batch N tool calls into one round-trip (JS) | @yawlabs/aws-mcp (aws_script) |
| Check IAM permissions before attempting an op | @yawlabs/aws-mcp (aws_iam_simulate) |
| Cross-account / cross-role in one session | Either -- this server takes any configured profile on every call and adds aws_assume_role for STS role-chaining; AWS's takes one per call over SigV4 only, from profiles declared when its proxy starts (an OAuth session is one role) |
| Sandboxed Python script execution server-side | AWS MCP Server (run_script) |
| Days-fresh API coverage via hosted endpoint | AWS MCP Server (run_script) |
| AWS-team-curated best-practice skills | AWS MCP Server (retrieve_skill) |
| Guided Lambda troubleshooting (diagnose, recent changes, trace summary) | AWS MCP Server (serverless capability) |
| Typed per-service helpers for what a CLI-based tool cannot reach (Bedrock agentic KB retrieval, ...) | awslabs/mcp (per-service servers) |
@yawlabs/aws-mcp and AWS's official server are an either/or -- pick the one whose tradeoffs fit. awslabs/mcp per-service servers pair cleanly with whichever you pick.
What this server borrows from AWS's official one
Credit where due -- two features here were shaped by the official AWS MCP Server:
aws_scriptmirrors the official server'srun_script: a scripting tool that collapses "list X, fetch Y for each, return Z" pipelines into one round-trip. Theirs is Python, sandboxed server-side, and is now that server's only general-purpose API path; this one is JS-native, runs in this server's own process -- see the trust note in the tools table -- and sits besideaws_callrather than replacing it.aws_docs_search/aws_docs_readwere added so you don't need a separate docs MCP whichever server you pick. They cover the same ground as the official server'ssearch_documentation/read_documentation-- live search and page reads -- without its topic routing or skills results.
The rest -- SSO device-code re-login, CCAPI CRUD with dry-run diffs, multi-region fan-out, IAM pre-flight checks -- is this server's own.
Tools
| Tool | What it does |
|---|---|
aws_whoami | Current identity (account, ARN) + SSO token expiry countdown. Call this first. |
aws_login_start | Start aws sso login --no-browser --use-device-code, returns a verification URL + short code and a sessionId. (--use-device-code is omitted on AWS CLI older than 2.22.0, where the device grant is already the default.) Or, with ssoSession + startUrl + ssoRegion, bootstrap an IAM Identity Center login with no profile -- see First-time setup without a profile. |
aws_login_complete | Block until the SSO subprocess finishes (you auth in your browser), returns the new identity (or, for an ssoSession login, the token status). |
aws_refresh_if_expiring_soon | Check the cached SSO token and auto-start a refresh when < thresholdMinutes remain (default 10). One round-trip for "am I about to expire? if so, re-login." |
aws_session_set | Set the default profile and/or region for the rest of this MCP session. "Switch to prod," "use us-west-2." |
aws_session_get | Show the current session defaults and where each value came from (session/env/default). |
aws_session_clear | Remove session profile/region overrides so env vars / defaults take over again. No args clears both. |
aws_list_profiles | List profiles configured in the AWS config file (AWS_CONFIG_FILE, else ~/.aws/config) -- names, regions, and SSO metadata. Use before switching profiles or when an SSO error names one you haven't seen. |
aws_sso_list_assignments | List the accounts and roles your Identity Center login can use, flagging which already have a profile. |
aws_sso_generate_profiles | Write [profile ...] sections for chosen (or all) account/role assignments into the AWS config file; never touches sections it did not create. |
aws_assume_role | Call STS AssumeRole with your current identity and stash the temp creds as a new profile (mcp-<sessionName>) in ~/.aws/credentials. Use for cross-account access. The secret/session token stay on disk -- not returned to the model. Optional timeoutMs (default 120s) for slow SAML / credential_process cold starts. |
aws_call | Run any AWS API operation. service: 's3api', operation: 'list-buckets', optional params (PascalCase JSON), optional query (JMESPath). Returns parsed JSON. Hand-written CLI commands (s3 cp/ls/sync, logs tail) and operations that stream their response to a file (s3api get-object, bedrock-runtime invoke-model, bedrock-agentcore invoke-agent-runtime, lambda invoke) never accept --cli-input-json, so aws_call cannot reach them; the error says so and names the alternative (aws_lambda_invoke, aws_logs_tail, bedrock-runtime converse, or a shell). Waiters work as operation: 'wait <name>'. Blob-typed params take base64. |
aws_paginate | Fetch one page of a paginated list/describe operation. Supports query too. Returns nextToken/hasMore; call again with the token to continue. |
aws_logs_tail | Fetch the newest CloudWatch Logs events for one log group (FilterLogEvents via aws logs filter-log-events), with since, filterPattern and stream-name filters; returns {timestamp, logStreamName, message} objects, oldest first. Bounded by maxEvents (default 500, max 10000): a busier window keeps the NEWEST events and reports truncated: true. On AWS CLI 2.35.8+ the read itself stops after maxEvents, so totalEvents is null when truncated; older CLIs scan the whole window and report the exact count. Accepts a log-group ARN in the call's region, sent as logGroupIdentifier, so a source-account ARN works from a cross-account monitoring account (needs AWS CLI 2.9.15+). |
aws_logs_query | Run a CloudWatch Logs Insights query end to end: StartQuery, poll GetQueryResults to a terminal status, return the rows -- one call instead of the start/poll/interpret-status dance. Takes logGroupNames (1-50, bare names or ARNs), queryString (Logs Insights QL, or PPL via queryLanguage), and the same startTime/endTime vocabulary as aws_metrics_query; window capped at 90 days, limit defaults to 1000. Rows come back FLATTENED from the API's [{field, value}] pairs into plain objects, alongside statistics (recordsMatched/recordsScanned/bytesScanned). Billed by uncompressed bytes scanned, so narrow the window before widening it. On timeout or client cancellation the query is never stopped -- the queryId comes back and results stay retrievable for 7 days. |
aws_metrics_query | Query CloudWatch metrics via GetMetricData (the modern multi-metric / expression-capable API). Pass queries: [{id, namespace, metricName, dimensions?, statistic?, period?}] or expression-based queries; startTime/endTime accept ISO 8601 or relative shorthand ('15m', '1h', '1d'). Period auto-picks from the time range. Returns {series: [{id, label?, timestamps, values, period?, statusCode?}], periodSeconds, profile, region, nextToken, hasMore, messages?} (full envelope under Stability). |
aws_resource_get | Read an AWS resource via Cloud Control API by typeName + identifier (e.g. AWS::Lambda::Function + function name). Returns parsed Properties. |
aws_resource_list | List resources of a type via CCAPI, paginated. Returns {identifier, properties} per entry plus a nextToken/hasMore. |
aws_resource_create | Create an AWS resource via CCAPI. Async — returns top-level requestToken + operationStatus. Pass awaitCompletion: true to have the server poll to terminal state in one call. |
aws_resource_update | Update an AWS resource via CCAPI using RFC 6902 JSON Patch. Same async + awaitCompletion shape as create. |
aws_resource_delete | Delete an AWS resource via CCAPI. Same async + awaitCompletion shape as create. Destructive — verify identifier first. |
aws_resource_status | Poll an async CCAPI request by requestToken. Returns the current state with operationStatus, identifier, errorCode, statusMessage flat-promoted (PENDING / IN_PROGRESS / SUCCESS / FAILED / CANCEL_*). |
aws_resource_diff | Dry-run a CCAPI update: fetches current state, simulates the JSON Patch in memory, returns {before, after, changes[]}. No mutation sent to AWS. Supports the add/remove/replace subset of RFC 6902; add auto-creates missing object parents to match CCAPI's actual update semantics (so patches like /Environment/Variables/NEW_KEY work even when /Environment/Variables doesn't exist yet). changes[i].after reflects what op i produced (not the final post-patch state), so sequential ops on the same path read correctly. Call before aws_resource_update when you want to verify the patch does what you expect. |
aws_multi_region | Run the same AWS operation across N regions in parallel. Same shape as aws_call but takes regions: string[]. Returns {region, ok, data?, error?}[] with okCount/errorCount. Partial failure is expected (services aren't everywhere, perms may be region-scoped). Up to 64 regions per call, at most 32 in flight. |
aws_multi_account | Run the same AWS operation across N accounts in parallel, assuming roleName in each. Credentials for every account are held IN MEMORY for the life of the call and passed to that one spawn -- nothing is written to ~/.aws/credentials, unlike an aws_assume_role loop, which either writes a section per account or stomps one repeatedly (and leaves live keys on disk if a sweep dies midway). Same envelope as aws_multi_region with accountId in place of region, including the 5 MB aggregate cap and okCount/errorCount computed before capping. Partial failure is expected: the role may not exist everywhere. |
aws_script | Run a short JS snippet that orchestrates the other tools and returns a combined result. Sandbox exposes aws.call, aws.paginate, aws.paginateAll, aws.resource.{get,list,create,update,delete,status}, aws.logsTail, aws.metricsQuery, aws.iamSimulate, aws.multiRegion, aws.assumeRole, aws.docs.{search,read}, plus standard JS builtins (JSON, Math, Date, Promise, etc.) and console. require/import/process/fs/fetch/timers are not bound into the context. This is not a security boundary: the script runs in this server's own process, and host globals remain reachable from inside it, so aws_script 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. Best for "list X, fetch Y for each, return Z" pipelines that would otherwise be N round-trips. Use return <value> to surface a result. |
aws_iam_simulate | Simulate IAM permissions for a principal: can principal X do actions Y on resources Z? Wraps iam simulate-principal-policy. Returns one entry per (action, resource) pair -- one per action with resource * when resources is omitted -- with decision (allowed / explicitDeny / implicitDeny / unknown), matchedStatementIds (which IAM statements decided), missingContextValues (context keys the policy needed but you didn't provide), permissionsBoundaryDecision and organizationsDecision (reported by AWS per action). An SCP deny never names its statement, and keys only an SCP references are never reported missing -- pass aws:RequestedRegion and the like in contextEntries. "allowed" is necessary, not sufficient: RCPs, the target resource's own policy, session policies and VPC endpoint policies are not evaluated. Pass the IAM role ARN, not the STS session ARN aws_whoami shows. Use BEFORE a risky operation to avoid a 403 -- pairs with the post-failure Suggestion from aws_call. Requires iam:SimulatePrincipalPolicy on the caller. |
aws_lambda_invoke | Invoke a Lambda function synchronously and return its response payload plus the DECODED tail of its execution log. aws_call structurally cannot do this -- aws lambda invoke takes the response body as a required positional outfile and rejects --cli-input-json -- so this is the one Lambda path that works without a second (Python) MCP server. The decoded logTail collapses the usual invoke -> find the log group -> tail it -> hope the window caught it loop into one call. A non-empty functionError means the function's HANDLER threw: the invocation still succeeded, so ok is true and the thrown error is in payload. The invoke is sent at most once: the CLI's automatic retries are off for this tool, because a retried invoke runs the function again. timeoutMs is how long to wait for the function (default 60s, at most 900000). A throttled call did not run and is safe to retry; after a timeout the error says whether the invoke was sent. |
aws_docs_search | Search live AWS documentation (the backend behind the docs.aws.amazon.com search box). Returns ranked {title, url, summary, excerpt}. Each result also carries a locally computed lexicalMatch, and the response carries queryTerms / termsMatchedNowhere / bestLexicalOverlap / lowRelevance -- the backend always returns a full page of fuzzy matches and never says "no good match", so those are the only signal that a query found nothing. Use to discover the right doc page for a service/API/concept the model may not know -- new services, recently changed APIs, exact parameter names. |
aws_docs_read | Fetch an https://docs.aws.amazon.com/...html page and return it as markdown. Strips nav/cookie-banner/feedback chrome. Long pages paginate via startIndex + maxLength; the response carries hasMore and nextStartIndex. Usually fed a url from aws_docs_search. |
Install
Add to your MCP client config (e.g. .mcp.json):
{
"mcpServers": {
"aws": {
"command": "npx",
"args": ["-y", "@yawlabs/aws-mcp@latest"]
}
}
}
Keep the key aws (anything but aws-mcp). AWS's aws configure agent-toolkit wizard registers its hosted server under aws-mcp, and reports an existing aws-mcp entry as already configured without looking at what it runs.
The -y flag is what gives you auto-update on each session load: every time your MCP client spawns the server, npx checks the registry for the latest @yawlabs/aws-mcp and downloads it if newer. The first launch in a fresh cache adds ~100-500 ms; subsequent launches use npm's cache (typical metadata-freshness window: 5 min) and add ~50 ms or less. Once the server is up, tool calls have zero auto-update overhead -- the check fires only on (re-)spawn. No separate install step is needed; -y covers both first-time install and ongoing updates.
If you'd rather pin a specific version (no auto-update, but zero startup overhead), install globally and point the config at the installed binary:
npm install -g @yawlabs/aws-mcp
{
"mcpServers": {
"aws": {
"command": "aws-mcp"
}
}
}
You'll need to npm install -g @yawlabs/aws-mcp@latest manually when you want a newer version.
Example session
You ask the assistant to check a staging bucket, but your SSO token just expired. What the assistant does (and what you see):
You: "How many objects are in the staging-artifacts bucket right now?"
Claude: (calls aws_whoami) -> SSO session expired for profile 'staging'.
(calls aws_login_start with profile='staging')
"Your SSO token expired. Open
https://device.sso.us-east-1.amazonaws.com/
and enter code: ABCD-EFGH
I'll wait."
You: *click, authenticate in your browser*
Claude: (calls aws_login_complete with the sessionId)
(calls aws_call with service='s3api', operation='list-objects-v2',
params={ Bucket: 'staging-artifacts' },
query='KeyCount')
"There are 4,182 objects in staging-artifacts."
The SSO flow took one click. No "the browser didn't open, let me run it in a terminal" context switch.
For a larger list -- anything that would run past your MCP host's output limit, which is far smaller than this server's 5 MB cap -- the assistant reaches for aws_paginate:
(calls aws_paginate with service='ec2', operation='describe-instances',
maxItems=50,
query='Reservations[].Instances[].{Id:InstanceId,State:State.Name}')
-> returns one page + a nextToken; Claude calls again until hasMore=false
query (JMESPath) trims the response server-side -- a typical describe-instances result shrinks from megabytes to kilobytes when you only need two fields.
For "create this resource and tell me when it's ready," aws_resource_create with awaitCompletion: true collapses the usual create-then-poll loop into one tool call:
(calls aws_resource_create with
typeName='AWS::SSM::Parameter',
desiredState={Name: '/my/param', Type: 'String', Value: 'hello'},
awaitCompletion: true)
-> server polls get-resource-request-status until SUCCESS / FAILED / CANCEL_COMPLETE
and returns the terminal ProgressEvent in one call
Same shape for aws_resource_update and aws_resource_delete. Drop awaitCompletion (or set it false) for the default fire-and-poll behavior -- useful when you want to kick off a long-running update and check back later.
For "preview the patch before applying":
(calls aws_resource_diff with
typeName='AWS::Lambda::Function',
identifier='my-fn',
patchDocument=[{op: 'replace', path: '/MemorySize', value: 1024}])
-> returns { before: {MemorySize: 256, ...}, after: {MemorySize: 1024, ...},
changes: [{op: 'replace', path: '/MemorySize', before: 256, after: 1024}] }
No mutation is sent to AWS; the agent can verify the patch before invoking aws_resource_update.
For batched workflows, aws_script collapses N tool calls into one:
(calls aws_script with code=`
const listed = await aws.resource.list({ typeName: "AWS::Lambda::Function" });
const big = [];
for (const r of listed.resources) {
const cfg = await aws.resource.get({
typeName: "AWS::Lambda::Function", identifier: r.identifier });
if (cfg.properties.MemorySize > 1024) {
big.push({ name: cfg.properties.FunctionName, mem: cfg.properties.MemorySize });
}
}
return big;
`)
-> one round-trip; the agent gets the filtered list without N intermediate tool calls
For multi-region reads:
(calls aws_multi_region with
service='ec2', operation='describe-instances',
regions=['us-east-1','us-west-2','eu-west-1'],
query='Reservations[].Instances[].InstanceId')
-> {okCount: 3, errorCount: 0, results: [{region, ok, data}, ...]}
Requirements
- Node.js 22+ (or oam.js -- see Runtime)
- AWS CLI v2 on
PATH. Every tool that talks to AWS shells out to it (all butaws_docs_*,aws_session_*andaws_list_profiles), so the CLI you have installed decides which services, operations and parameters are reachable. (aws_sso_generate_profileswrites the config file in-process but still shells out for the account/role discovery it runs first.) No minimum version is enforced, with one exception:- 2.22.0+ recommended. That release added
--use-device-code, which this server needs to keep the SSO short-code flow working. Older 2.x still works -- the server detects the version and adapts. - 2.9.0+ for a profile-free Identity Center login (
aws_login_startwithssoSession), which needsaws sso login --sso-session. On an older CLI that call is refused with an upgrade message; profile logins are unaffected. - Developed and tested against 2.34.3. Anything newer than your CLI is rejected by the CLI itself before a request is sent: an unknown service or operation as an "invalid choice" (the error then says to upgrade), a new parameter as
Unknown parameter in input. Upgrade withaws update(CLI 2.36.0+, for installs made with AWS's installer or install script), otherwise with the installer or your package manager. - Security, as of 2026-09: CLI 2.35.3 or newer clears every published AWS CLI v2 advisory (GHSA-747p-wmpv-9c78, CVE-2026-13769, CVE-2026-18654). None of the affected paths is reachable through this server: the four commands (
emr ssh/socks/put/get,codeartifact login,deploy register,iam create-virtual-mfa-device) all register no--cli-input-json, which is the only wayaws_callpasses parameters, and the third advisory is about the opt-incli_historydatabase, which this server never enables. You do share that CLI install with everything else on the machine, though. Worth checking the advisory list for newer ones: v2 ships as an installer, so a dependency scanner will never flag it. - AWS CLI v1 is unsupported; it entered maintenance mode on 2026-07-15 and reaches end of support on 2027-07-15.
- 2.22.0+ recommended. That release added
- An AWS profile the CLI can already use -- see Environment for how the profile is chosen. SSO / IAM Identity Center profiles also get the device-code re-login tools. No profile yet? An Identity Center start URL is enough -- see First-time setup without a profile.
Runtime
This server runs on oam.js and on Node, unmodified, and
the launcher never serves on an oam older than 0.20.2, and picks the newest
oam binary it can find at or above that floor. Verified on oam 0.20.2
(aarch64-pc-windows-msvc): full MCP handshake listing all 30 tools, a local tool
call, and the aws_script sandbox behavior described below.
oam 0.20.2 is the minimum. The launcher picks the newest oam it can find at
or above it, never serves on an older one, and falls back to Node when there is
none (AWS_MCP_RUNTIME=oam turns that into a hard error). A floor matters here:
releases before 0.9.0 ran child_process.execFile arguments through a shell,
accepted exec's timeout and ignored it, and treated stdio: 'inherit' as
'pipe', and this server shells out to the aws CLI on essentially every tool.
To run it under oam, point your MCP client's command at it:
{
"mcpServers": {
"aws": {
"command": "oam",
"args": ["run", "/path/to/aws-mcp/dist/index.js"],
"env": { "AWS_PROFILE": "my-sso-profile", "AWS_REGION": "us-west-2" }
}
}
}
Measure startup on your own hardware. An MCP client cold-starts this server
once per session, so startup is the cost that actually gets paid. The numbers
below were taken with oam 0.8.2, long before the current 0.20.2 floor, and have
not been re-run since, so do not read them as a current ranking. To a completed
initialize + tools/list handshake, median of 10 warmed runs:
| Runtime | Cold start |
|---|---|
node dist/index.js | 359 ms |
oam run dist/index.js | 650 ms |
oam run src/index.ts (no build step) | 947 ms |
The published aws-mcp command prefers the newest oam it finds (see
AWS_MCP_RUNTIME under Environment). Without oam that costs
almost nothing: discovery is file-existence checks only, never a subprocess, and
the fallback runs the server inside the Node process npm already started. With
oam installed, though, the command boots Node, runs --version on every oam
binary it found to pick the newest, and only then boots oam, so it is always
slower than pointing your client at oam directly with the config above.
AWS_MCP_RUNTIME=node skips oam entirely.
Two more places oam wins for this repo, both opt-in and neither touching the published npm package:
npm run check:oam-- type-checks viaoam check(tsgo, TypeScript 7 native). Measured ~1.0s against ~3.8-4.7s fortsc --noEmit, resolving the sametsconfig.jsonand covering the same files -- including tests, confirmed by planting a type error in a test file and watching both reject it.npx tsc --noEmitremains the portable default.npm run build:binary:oam-- builds the standalone binary viaoam compile. Measured 58.60 MB on win32-arm64, including ~493 KB of embedded V8 bytecode. Writes tobin/<platform>-<arch>/, which the release staging script consumes. If you redistribute that binary it embeds oam's runtime, so ship oam'sLICENSE,NOTICEandTHIRD_PARTY_LICENSES.mdwith it.
The source stays runtime-agnostic on purpose: no oam: imports anywhere, and
tests stay on node:test. That is what keeps the Node fallback real rather than
nominal.
One behavioral difference worth knowing if you run aws_script under oam: Node
honors codeGeneration: { strings: false } on the node:vm context, so eval
and Function throw; oam does not, so they work. Re-measured against oam 0.20.2
and still divergent -- inside the sandbox, eval('1+1') returns 2 and
Function('return 7')() returns 7 under oam, while both raise EvalError under
Node -- so treat it as a standing difference. The containment that
matters is unaffected -- under oam, Function('return this')() yields a global
whose process and require are both undefined, and Function('return require') throws -- so a script gains nothing it couldn't already do by writing
the same code in its body. aws_script was never a security boundary (see its
description); the shadowed-globals list is the real defense, not that flag.
Note that any oam invocation writes a bytecode cache to oam/ in the working
directory -- already in .gitignore.
Environment
| Variable | Default | Purpose |
|---|---|---|
AWS_PROFILE / AWS_DEFAULT_PROFILE | default | Profile used when a tool call omits profile. AWS_DEFAULT_PROFILE is the legacy spelling. AWS_PROFILE wins if both are set, as in AWS CLI v2 (standalone botocore and boto3 check AWS_DEFAULT_PROFILE first). An empty value counts as unset. |
AWS_REGION / AWS_DEFAULT_REGION | us-east-1 | Region used when a tool call omits region. AWS_REGION wins if both are set. |
AWS_CONFIG_FILE | ~/.aws/config | The AWS config file. The CLI reads it for every call; aws_list_profiles and the SSO start-URL lookup in aws_whoami / aws_login_complete / aws_refresh_if_expiring_soon read the same file. Resolved like botocore: $VAR / ${VAR} (and %VAR% on Windows) are expanded, then a leading ~. A set-but-empty value means no config file, as it does for the CLI. aws-mcp also WRITES it: the [sso-session] block from aws_login_start with ssoSession, and the profiles from aws_sso_generate_profiles -- same semantics as the AWS CLI. The SSO token cache has no such variable: it always lives under the home directory (HOME on macOS / Linux, USERPROFILE on Windows), so a per-user gateway on Windows must set USERPROFILE, not only HOME. |
AWS_SHARED_CREDENTIALS_FILE | ~/.aws/credentials | Where aws_assume_role writes the profile it creates. Resolved the same way as AWS_CONFIG_FILE, so the write lands in the same file the CLI later reads. |
AWS_MCP_AWS_CLI | unset | Absolute path to the aws executable to run instead of the one found on PATH. For MCP hosts started from a GUI, which often inherit none of your shell's PATH -- and AWS's recommended installer now defaults to ~/.local/bin on macOS and Linux, which such hosts rarely see. Find the path with command -v aws (macOS/Linux) or where.exe aws (Windows). In Git Bash on Windows use where.exe aws, not command -v aws: the latter prints a POSIX-style path (/c/Program Files/...) that this variable refuses, because it must be a native absolute path. It applies to every call and to aws sso login. Must be absolute, and on Windows must name aws.exe: a .cmd or .bat shim cannot be started without a shell. An unusable value fails every call with a message naming this variable, rather than quietly running a different CLI than you configured. Unset, the server walks the absolute directories on PATH; it never runs an aws from its working directory. |
Documentation truncated — see the full README on GitHub.
Reviews
No reviews yet
Be the first to review this server!
More Cloud & DevOps MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Lharries · Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions
