Query and manage AWS across multiple accounts/orgs through your IAM Identity Center login, with roles chosen only by your TOML rules.
Query any AWS service/API via generic aws_query, fanning out across selected accounts and merging/redacting results.
Select accounts by org, id, name, substring, environment, with exclusions and blast-radius caps.
Run multi-step declarative DAG queries per account, including referencing earlier step outputs.
Manage SSO sessions: list/switch orgs, check token/cache status, login only when explicitly requested, and refresh the account directory.
Search cached accounts and list IAM roles available on an account.
Explain deterministic role selection for an account without making AWS calls.
Inspect and validate configuration; view performance/cache stats.
Perform write/delete operations if the assumed IAM role permits; destructive operations require confirmation. AWS IAM is the only authorization boundary.
Audit calls to a local JSONL log and redact secrets from output/logs on a best-effort basis.
Integrates with AWS Organizations and IAM Identity Center to query and manage resources across multiple AWS accounts and orgs. It supports selecting accounts by org, name, ID, substring, or environment, applying config-defined IAM roles, fanning out AWS API calls in parallel, and returning merged, redacted results.
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-sso-mcp List all EC2 instance statuses across my organization."
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.
Got more than one AWS account or org? Sign in once, ask in plain English, and get one merged answer from all of them, using the IAM roles your rules choose, never the AI's.
aws-sso-mcp is an MCP (Model Context Protocol) server. It plugs
into a chat assistant such as GitHub Copilot Chat in VS Code or Claude Desktop, and lets that
assistant query and manage AWS through your AWS IAM Identity Center (SSO) login.
"List all stopped EC2 instances across every prod account in org1."
One sentence in. One combined answer out, from every matching account.
Related MCP server: Sandy
If you work in more than one AWS account, yes. The more accounts and orgs you have, the more it saves you.
Several orgs. Keep every org in one config file. Switch between them in chat, or query several in a single request. Each org needs its own login, and you never mix them up by accident.
Dozens or hundreds of accounts. Find accounts by name, id or environment, then ask one question of all of them. No account-by-account console hopping, no profile juggling.
A different role per account. Prod gets ReadOnlyAccess, sandboxes get PowerUserAccess.
You write that once, and it is applied everywhere.
Questions that cross accounts. "Where is this running?", "Which accounts have public buckets?", "What is stopped in prod?" Each is one sentence instead of an afternoon of clicking.
If you only ever use a single account, it still works, but a plain AWS CLI profile is simpler.
Companies often have tens or hundreds of AWS accounts, spread over several AWS Organizations. Answering "where is X running?" normally means logging in to each account in turn.
This server removes that grind:
Without it | With it |
Sign in to every account, one by one | Sign in once per organization |
Remember which IAM role to use in which account | Roles are chosen by rules you write in a config file |
Run the same CLI command N times | One request fans out to all N accounts in parallel |
Copy and merge the outputs yourself | One merged, sorted, redacted result |
Query any AWS service. One generic tool (aws_query) takes the same service and operation names
as the AWS CLI and boto3, for example ec2 and DescribeInstances. There are no per-service tools to
wait for.
Select accounts flexibly. Pick by org, exact name, id, name substring, or an environment
(prod, staging, dev) that you define. Exclusions are supported.
Chain steps. run_dag runs a small multi-step plan per account. For example, list the instances,
then describe their volumes using the first step's output.
Manage sessions. Log in, switch org, check token status, search the cached account directory.
Audit everything. Every call is appended to a local JSONL audit log.
flowchart TD
You([You]) -->|1. ask in plain English| Chat[Chat assistant<br/>Copilot, Claude, ...]
Chat -->|2. MCP tool call over stdio| MCP[aws-sso-mcp]
MCP -->|3. sign in once, device login| IDC[AWS IAM Identity Center]
IDC -->|4. short-lived role keys<br/>kept in memory only| MCP
MCP -->|5. API calls, in parallel| ACC[Your AWS accounts<br/>EC2, S3, IAM ...]
ACC -->|one reply per account| MCP
MCP -->|6. merged, redacted result| Chat
Chat -->|7. answer in plain English| YouThe full, step-by-step explanation (with code references) is in docs/how-it-works.md. The detailed connectivity diagrams are in docs/architecture.md.
You need Python 3.12+ and uv.
For the full walkthrough, see docs/setup-guide.md.
1. Install
uv tool install aws-sso-mcp # or: pipx install aws-sso-mcp
aws-sso-mcp --version2. Create your config (references only, never secrets)
mkdir -p ~/.config/aws-sso-mcp
curl -fsSL https://raw.githubusercontent.com/arnabdas24/aws-sso-mcp/main/examples/config.example.toml \
-o ~/.config/aws-sso-mcp/config.tomlEdit it and set your start_url and region per org. The minimum is:
default_org = "org1"
[portals.org1]
start_url = "https://your-org1.awsapps.com/start"
region = "us-east-1" # where your Identity Center lives, NOT where you query
[portals.org1.environments.prod]
match = "endswith"
patterns = ["-prod"]
roles = ["ReadOnlyAccess"]On Windows, use %USERPROFILE%\.config\aws-sso-mcp\config.toml, or point AWS_SSO_MCP_CONFIG at any path.
3. Register it with your chat client (VS Code example, in your user mcp.json)
{
"servers": {
"aws-sso-mcp": { "type": "stdio", "command": "aws-sso-mcp" }
}
}Claude Desktop, Claude Code, Cursor, Windsurf and non-default config paths are all covered in docs/setup-guide.md.
4. Chat
In Agent mode, try:
Log in to org1. A browser opens once for approval.
Find accounts with "prod" in the name.
List stopped EC2 instances in us-east-1 across every prod account.
More ready-made phrasings, plus mistakes to avoid, are in docs/prompt-guide.md. To see the exact tool call behind each sentence, read docs/examples.md.
Read this before pointing the server at real accounts.
Good to know: it works with exactly the permissions you have.
The server signs in through IAM Identity Center and inherits the permission set of the role you choose. It can see and do what that role allows in IAM, no more and no less, and IAM is the only gate. That is what keeps it simple and predictable. A few habits make it even safer:
Pick a read-only role.
ViewOnlyAccess,ReadOnlyAccessor a custom least-privilege set is ideal for everyday questions, and is all most people need.Know what the role can read. Read-only roles may still reach some sensitive data, such as S3 objects or Lambda environment variables. Output is redacted on a best-effort basis.
Treat AWS text as untrusted. Tags, names and log lines can contain odd instructions, so skim results before acting on them.
Glance at wide requests. The server asks you to confirm large selections.
Property | What it means |
IAM is the only gate | The server does not block writes locally. If your SSO role may delete something, a request can delete it. Use read-only roles in your config unless you truly need more. |
Your TOML is the only role selector | Neither the AI model nor a prompt can pick or override a role. Only your environment rules do, and an account that matches no rule is refused (see roles.py). |
No surprise browser windows | Only the |
Blast-radius cap | A selection wider than |
Secrets are redacted | Tokens and keys are scrubbed from logs and tool output (redact.py). Credentials are never written to disk. |
Config cannot hold secrets | The loader rejects keys that look like secrets (config.py). |
Everything is audited | One line per call in |
AWS response data (tags, names, log lines) is untrusted text that reaches the model. This server bounds its size but cannot remove prompt-injection attempts. Details in docs/architecture.md.
Document | Read it if you want to... |
Understand, step by step and in plain language, what happens from your sentence to the answer | |
See connectivity diagrams, components, threads, storage and security layers | |
Contributor map of the code: who calls what, every cache and lock, known quirks, debugging cookbook | |
Learn what to say to your assistant, with copy-paste examples | |
Look up every tool, argument and response shape | |
Configure orgs, environments, roles and performance | |
Set up, test, extend and release the project | |
Understand why a design decision was made, and what it cost | |
Fix a specific error message | |
Contribute code: setup, quality gates, commit conventions | |
Report a vulnerability, or review the threat model | |
Install and wire up the server in various MCP clients |
src/aws_sso_mcp/
├── server.py # MCP tools (thin entry points)
├── fanout.py # the shared multi-account pipeline
├── planner.py # which accounts? (selectors -> targets)
├── roles.py # which role? (deterministic rules)
├── state.py # per-process session state
├── config.py # TOML loading and validation
├── audit.py # append-only JSONL audit log
├── redact.py # secret scrubbing
├── hardening.py # output size caps + redaction in one pass
├── logging_setup.py # stderr + chat-UI logging
├── awscfg.py # cached boto3 client factory
├── errors.py # clean, user-facing exception types
├── sso/ # login (device_auth), credentials (broker), directory
├── cache/ # SQLite account/role cache
└── engine/ # catalog (one AWS call), dag (multi-step), executor (threads)Python 3.12 or newer, boto3, and the mcp SDK (see pyproject.toml).
Alpha (0.1.x): interfaces may change.
Transport is stdio. The server is started by your chat client, one process per session.
Credentials are brokered, never stored on disk; see Safety model and the full threat model in SECURITY.md. Report vulnerabilities privately via GitHub Security Advisories, not public issues.
Releases are built by GitHub Actions with PyPI Trusted Publishing and carry a signed SLSA build-provenance attestation plus a CycloneDX SBOM:
gh attestation verify ./aws_sso_mcp-<version>-py3-none-any.whl --repo arnabdas24/aws-sso-mcpSee CONTRIBUTING.md. Every change must pass ruff, mypy --strict, the test
suite with its global and per-module coverage floors, and vulture.
Apache License 2.0. Releases up to and including 0.1.1 were published under the MIT License and remain available under it.
Run one AWS API call across every account a selector resolves to.
``service``/``operation``/``params`` follow the AWS CLI and botocore shape,
e.g. ``service="ec2"``, ``operation="DescribeInstances"``,
``params={"Filters": [{"Name": "instance-state-name", "Values": ["stopped"]}]}``.
Paginated operations are followed to completion automatically, so results
are complete rather than a silent first page. If a result is truncated,
raise ``max_items`` to collect more from each account.
``region`` is always required and never defaulted. Account selectors decide
which accounts are touched; with none given, every account in the active org
is targeted, subject to the configured blast-radius cap. The model never
picks which IAM role to assume, and neither does the caller: the role comes only
from the ``[portals.<org>.environments.*]`` rules in your TOML config.
Any operation the assumed role may perform is dispatched - reads, writes,
deletes, secret reads, all of it - with AWS IAM as the sole authorization
boundary. Nothing is refused locally; if the role lacks permission, AWS
returns AccessDenied and that is what comes back.
Operations that delete, terminate or detach something (``Delete*``,
``Terminate*``, ``Remove*``, ``Detach*`` and similar) first ask the user to
confirm, listing the accounts and parameters. If they decline, or the client
cannot ask, nothing runs. Do not retry a declined call.
Inputs: region (required), service (required), operation (required), org, +12 more. Returns: object
Report cache freshness for one org, or every configured org.
Inputs: org. Returns: object
Show the resolved, loaded configuration (it never contains secrets).
Inputs: no named parameters. Returns: object
Re-load and validate the config file, reporting errors without applying them.
Inputs: no named parameters. Returns: object
Report the currently active org, if any.
Inputs: no named parameters. Returns: object
Dry-run deterministic role resolution for one account; makes no service call.
Shows exactly which role the TOML environment rules would assume. The role is never chosen by the model or by the caller, and there is no override argument.
Inputs: account_id (required), account_name (required), org. Returns: object
List the IAM roles granted to you on one account, via that account's SSO portal.
Inputs: account_id (required), org, force_refresh. Returns: object
Authenticate to an org via SSO device authorization (opens a browser for approval).
This is the only tool that will ever open a browser. Queries never start a sign-in on your behalf; they fail with a message telling you to call this first, so a browser window never appears unexpectedly mid-query.
Inputs: org. Returns: object
List every org configured in the aws-sso-mcp TOML config.
Inputs: no named parameters. Returns: object
Report token validity and cache freshness for an org (defaults to the active org).
Inputs: org. Returns: object
Report cache hit/miss counts and executor sizing for the running server.
Answers "why was that fan-out slow?" without turning on debug logging. A high credential-broker miss rate points to short-lived sessions or role churn; a high role-cache miss rate suggests the directory TTL is too short.
Inputs: no named parameters. Returns: object
Force a refresh of the cached account directory for one org, or every configured org.
Inputs: org, all_orgs. Returns: object
Run a small declarative multi-step query DAG against every resolved account.
Each entry in ``steps`` is
``{"id": ..., "service": ..., "operation": ..., "params": {...},
"extract": "...", "depends_on": [...]}``.
A later step's ``params`` may reference an earlier step's extracted output
anywhere a literal would go, via ``{"$ref": "<step_id>"}``. There is no
expression language and nothing is ever evaluated as code.
Every resolved account runs its own independent copy of the whole DAG, with
one credential mint per account rather than one per step. As with
``aws_query``, AWS IAM is the sole authorization boundary for every step,
and ``max_items`` raises the per-account pagination ceiling for every step.
If any step deletes, terminates or detaches something, the user is asked to
confirm the whole DAG first; if they decline, nothing runs.
Inputs: steps (required), region (required), org, orgs, +10 more. Returns: object
Search the cached account directory by exact name, substring, or account id.
The cache is refreshed automatically per org if it is missing or older than
the configured TTL. ``name_contains`` is a case-insensitive substring and
behaves identically to the ``name_contains`` selector on ``aws_query``, so
what you find here is exactly what a query will target.
Inputs: org, name, limit, all_orgs, +2 more. Returns: object
Check cached SSO token validity WITHOUT ever opening a browser.
Inputs: org. Returns: object
Set the active org for this session (one-off org= overrides still win).
Inputs: org (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
Most tools map to clearly distinct actions: aws_query vs run_dag (single call vs multi-step DAG), explain_role_selection vs list_roles (dry-run rule resolution vs listing actual roles), and login vs refresh_accounts are all unambiguous. The main blur is org_status, which duplicates the coverage of token_status and cache_status, leaving an agent unsure which of the three to call. orgs_list/current_org/use_org are clean enough despite being in the same area.
Multiple conventions coexist: verb_noun (use_org, refresh_accounts, search_accounts, list_roles, run_dag), noun_noun (perf_stats, org_status, token_status, cache_status), noun_verb (orgs_list, config_show, config_validate), and bare nouns (login, current_org). The singular/plural mismatch (orgs_list vs list_roles) and status-noun shortcuts add to the inconsistency. Names remain individually readable, so it is mixed rather than chaotic.
16 tools is just above the comfortable band, but the surface splits into coherent groups (auth, org selection, account cache, roles, querying, config, perf) where each group serves a real need. The one clearly redundant entry is org_status, which a trim could fold into token_status/cache_status. Slightly heavy but justified for an SSO + fan-out query server.
The lifecycle is well covered: login, token_status/org_status for auth health, org selection, account cache refresh/search, role inspection, aws_query and run_dag for reads and writes, plus config show/validate and perf stats. The notable gaps are no logout/token revocation and no config mutation tool, though config editing via a file is arguably out of scope. These are minor, workable omissions rather than dead ends.
Unified API to query AWS, GCP, Azure and generate Terraform/CLI execution kits for AI agents.
Call AI by role, not by model: tiered AI gateway over REST and MCP.
Run every client's AI from one console: workspaces, roles, MCP tools, approvals and spend.
AI routing, memory, guardrails, and governance. Routes across Claude, GPT, Gemini.