@yawlabs/aws-mcp
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AWS_REGION | No | Region used when a tool call omits region. AWS_REGION wins if both AWS_REGION and AWS_DEFAULT_REGION are set. | us-east-1 |
| AWS_PROFILE | No | Profile used when a tool call omits profile. | default |
| AWS_DEFAULT_REGION | No | Fallback region if AWS_REGION is not set. | us-east-1 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
AWS through the locally installed aws CLI, using the caller's own profiles. Start with aws_whoami to confirm the identity and SSO token; if it reports an expired SSO session, use aws_login_start then aws_login_complete; aws_refresh_if_expiring_soon renews it ahead of a long task. aws_list_profiles lists profiles. A new IAM Identity Center user with no profile: aws_login_start with ssoSession, startUrl and ssoRegion, then aws_sso_list_assignments and aws_sso_generate_profiles. aws_session_set pins a profile and region for later calls (aws_session_get shows them, aws_session_clear resets). Any single API operation: aws_call. One page of a list or describe operation: aws_paginate. The same operation across regions or accounts: aws_multi_region or aws_multi_account. Many dependent calls with filtering or aggregation: aws_script, one snippet instead of many round trips. Resources by CloudFormation type name (AWS::Service::Resource): aws_resource_list and aws_resource_get to read; aws_resource_diff to preview a patch before aws_resource_update; aws_resource_create and aws_resource_delete; aws_resource_status to poll a change those return. Logs: aws_logs_tail for recent lines, aws_logs_query for CloudWatch Logs Insights. Metrics: aws_metrics_query. Permissions: aws_iam_simulate. Lambda: aws_lambda_invoke. Temporary role credentials as a named profile: aws_assume_role. AWS documentation: aws_docs_search, then aws_docs_read on a result.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| aws_whoamiA | Show the current AWS identity (account, role ARN, user ID) plus SSO token status and time remaining. Use this first to verify auth before running other AWS operations. Returns a structured fix-it message if SSO is expired. |
| aws_login_startA | Start an AWS SSO login via the device-code flow (no browser spawned from this process). Returns a verification URL and short code -- surface these to the user so they can open the URL in their own browser and paste the code. After they auth, call aws_login_complete with the returned sessionId to confirm completion. For a user with NO profile yet, pass ssoSession plus startUrl and ssoRegion instead of profile: this writes a managed [sso-session] block to the AWS config file (never touching one the user wrote) and logs in to IAM Identity Center directly; then use aws_sso_list_assignments and aws_sso_generate_profiles. |
| aws_login_completeA | Block until the SSO login started by aws_login_start finishes (user completed auth in browser, or subprocess exited with error). Returns the new identity on success, or a structured error. For an ssoSession login there is no profile yet, so it returns the token status and points to aws_sso_list_assignments instead of an identity. |
| aws_refresh_if_expiring_soonA | Proactive SSO token check. If the cached token has fewer than |
| aws_session_setA | Set the default AWS profile and/or region for the rest of this MCP session. Subsequent calls to aws_whoami, aws_login_*, and other AWS tools will use these values unless they override explicitly. Use when the user says 'switch to prod', 'use us-west-2', 'look at the staging account', etc. Both params are optional; pass whichever changed. Returns the resulting session state. |
| aws_session_getA | Show the current session's default AWS profile and region, and where each value came from ('session' = set by aws_session_set, 'env' = AWS_PROFILE/AWS_REGION env var, 'default' = built-in fallback). Useful for confirming state before running operations or debugging why a call hit the wrong account. |
| aws_session_clearA | Remove session-set profile and/or region overrides so subsequent calls fall back to env vars / defaults. No args clears both. Pass |
| aws_callA | Run an arbitrary AWS API operation via the aws CLI. Use kebab-case service and operation names as in |
| aws_list_profilesA | List AWS profiles configured in the AWS config file (AWS_CONFIG_FILE, else ~/.aws/config). Returns profile name, region, and SSO metadata (start URL, region, session name) where set, plus an |
| aws_sso_list_assignmentsA | List the AWS accounts and roles an IAM Identity Center login can use, after aws_login_start + aws_login_complete with ssoSession. Read-only. Each role shows |
| aws_sso_generate_profilesA | Write [profile ...] sections into the AWS config file for IAM Identity Center account/role assignments (after aws_login_start with ssoSession). Default: every assignment, capped at 200 (the rest are returned as |
| aws_paginateA | Fetch one page of a paginated AWS list/describe operation. Identical to aws_call plus |
| aws_assume_roleA | Call STS AssumeRole and stash the returned temporary credentials as a named profile in the shared credentials file ($AWS_SHARED_CREDENTIALS_FILE when set, otherwise ~/.aws/credentials; the resolved path is returned as credentialsPath). Subsequent calls to aws_call / aws_whoami / aws_paginate can use profile='mcp-' (or your overridden targetProfile name). The raw secret key / session token are NOT returned to the caller — only the profile name, expiration, and assumed identity. Use for cross-account access: a source profile (your SSO identity) assumes a role in another account. Default timeout is 120s (raise via timeoutMs for slow SAML / credential_process setups on cold start). |
| aws_logs_tailA | Fetch the newest CloudWatch Logs events for one log group over the last |
| aws_logs_queryA | Run a CloudWatch Logs Insights query and wait for it to finish -- StartQuery, poll GetQueryResults until the query reaches a terminal status, return the rows -- in ONE call, replacing the three-step start/poll/interpret-status dance you would otherwise write with aws_call. |
| aws_metrics_queryA | Query CloudWatch metrics via GetMetricData (the modern multi-metric / expression-capable API, not the legacy get-metric-statistics). Pass |
| aws_resource_getA | Read a single AWS resource via Cloud Control API. Covers hundreds of resource types with a CloudFormation schema. |
| aws_resource_listA | List resources of a given type via Cloud Control API, paginated. Returns an array of {identifier, properties}, a |
| aws_resource_createA | Create an AWS resource via Cloud Control API. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a |
| aws_resource_updateA | Update an AWS resource via Cloud Control API using RFC 6902 JSON Patch. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a top-level |
| aws_resource_deleteA | Delete an AWS resource via Cloud Control API. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a top-level |
| aws_resource_statusA | Poll the status of an async Cloud Control API request (create/update/delete). Pass the |
| aws_resource_diffA | Dry-run a CCAPI update: fetch the current resource state, simulate applying a JSON Patch in memory, and return before/after plus a flat list of changed paths. No mutation is sent to AWS. Use this before aws_resource_update to verify the patch does what you expect. Supports the add/remove/replace subset of RFC 6902 (covers the vast majority of CCAPI updates); 'move'/'copy'/'test' are rejected at schema validation -- use aws_resource_update directly if you need those (CCAPI accepts them, this preview tool just doesn't simulate them locally). |
| aws_multi_regionA | Run the same AWS API operation across multiple regions in parallel. Same shape as aws_call (service, operation, params?, query?, outputFormat?, timeoutMs?) but takes |
| aws_multi_accountA | Run the same AWS API operation across multiple ACCOUNTS in parallel by assuming the same role name in each. Same shape as aws_call (service, operation, params?, query?, outputFormat?, region?, timeoutMs?) plus |
| aws_iam_simulateA | Simulate IAM permissions for a principal: can principal X do actions Y on resources Z? Wraps |
| aws_lambda_invokeA | Invoke a Lambda function synchronously (RequestResponse) and return its response payload plus the DECODED tail of its execution log in one call. Use this instead of aws_call for Lambda invokes: |
| aws_docs_searchA | Search the live AWS documentation (the same backend that powers the docs.aws.amazon.com search box). Use this to discover the right doc page for a service, API, or concept the model may not know about -- new services, recently changed APIs, exact parameter names. Returns ranked results as {title, url, summary, excerpt}. IMPORTANT: that backend always returns a full page of fuzzy matches and has no way to answer 'no good match' -- a nonsense query still comes back with ten confident-looking hits. So each result also carries |
| aws_docs_readA | Fetch an AWS documentation page and return it as markdown. |
| aws_scriptA | Run a short JavaScript snippet that orchestrates other aws-mcp tools (aws.call, aws.paginate, aws.paginateAll, aws.resource.*, aws.logsTail, aws.metricsQuery, aws.iamSimulate, aws.multiRegion, aws.assumeRole, aws.docs.{search,read}) and returns a combined result. Best for batched read+filter+aggregate workflows that would otherwise need N tool round-trips: 'list all Lambdas, fetch each one's config, return those with memory > 1024'. Use |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 30 tools
Most tools have clearly distinct targets: session get/set/clear, login start/complete, resource CRUD, logs query vs logs tail vs metrics query. The fuzzy area is the generic-execution cluster — aws_call, aws_paginate, aws_multi_region, aws_multi_account and aws_script all 'run an API operation' — but each description explicitly states when to prefer it over aws_call, which resolves the overlap for an attentive agent. A few boundaries (aws_resource_get/list vs aws_call) require reading the description rather than the name alone.
Uniform `aws_` prefix and snake_case throughout, with a small set of clear domain prefixes (logs_, session_, resource_, sso_, docs_, multi_). The only wobble is word-order convention: some names are verb-first (assume_role, list_profiles, create/update/delete via resource_, generate_profiles) and others noun-first (logs_query, session_set, resource_get, iam_simulate). Both patterns are readable and consistent within their sub-families, so it is a minor deviation rather than a mixed-convention mess.
30 tools is on the heavy side for one server, sitting at the top of the '16-25 feels heavy' band and into 25+. The count is defensible because they span genuinely different domains (auth/SSO, session, generic execution, Cloud Control CRUD, logs, metrics, Lambda, docs, IAM simulation, multi-region/account fan-out), but a few could be folded — e.g. aws_paginate is aws_call plus two params, and aws_session_clear/get/set are three thin tools that could be one.
Coverage is broad and lifecycle-complete where it counts: full Cloud Control CRUD plus async status and a dry-run diff, SSO login start/complete, profile listing, role assumption, refresh, and session state control. Multi-region/multi-account fan-out, Lambda invoke with log tail, and a docs search/read pair round it out. Gaps are minor and mostly covered by the aws_call/aws_script escape hatches — no SSO logout, no removal of generated profiles, no query-cancel for aws_logs_query, and no first-class S3 data-plane operations.