cloud-harness-cli
Provides read-only, multi-account and multi-region AWS auditing and inspection tools: identity and account orientation (whoami, doctor, list_accounts, account_regions, console_url), compute/storage/network inventory (EC2 instances and details, S3 buckets and bucket info, VPCs), IAM hygiene (users, unused credentials, MFA checks), serverless and edge resources (Lambda functions, CloudFront distributions), security posture (GuardDuty findings, Security Hub status), Organizations accounts and OUs, backups (vaults and jobs), cost totals via Cost Explorer, and inventory summarization. Also exposes a safe_op_dry_run tool that returns the plan for a change without performing it, since the MCP surface cannot mutate AWS.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Cloud Harness CLI
Multi-account, multi-region AWS read and audit surface for a single operator. Written in Python/boto3. One capability set, two interfaces — a CLI you drive, and an MCP server your assistant drives.
Status. Phase 1 + 2 complete and exercised against live AWS. Read
by default; write access is limited to a small set of safe operations,
dry-run first, and is refused outright for businesses marked
read_only. No provisioning and no deletes — that remains Terraform
or CDK territory.
Why it exists. Navigating the AWS console across several accounts, businesses and regions costs more attention than the decision it supports. This harness replaces console navigation with typed verbs that can be scripted, audited and delegated to an assistant. See MOTIVATION.md.
pip install -e . --break-system-packages # or: pipx install .
harness doctor # credentials, regions, pluginsTwo interfaces, one capability set
The tool — | The server — | |
Who drives it | you: terminal, script, cron | your AI client |
How you talk to it | commands, flags, | 24 typed tools over JSON-RPC (stdio) |
Additional setup | none | one registration line in the client |
Can it change AWS | yes — safe operations, dry-run by default, | no — read and simulate only |
Output | tables or JSON, real exit codes | typed JSON, 50-row cap |
Typical use | routine work, audits, scheduled checks, scripting | "what exists, what is exposed, what does it cost" in prose |
Both surfaces call the same plugin methods. The MCP surface is deliberately the stricter subset of the CLI — see Safety model for why.
Tool, assistant, or both?
The harness ships no model, no prompt and no API key. Whether it acts as a tool or as an assistant depends entirely on what you attach to it:
Mode | Who drives it | Deterministic | Can change AWS |
Plain CLI | you — terminal, script, cron | yes | yes ( |
| you, in prose | yes — a router that can only select commands which exist, and refuses when arguments are missing | yes ( |
CLI + MCP client with a model | the model, through 24 typed tools | no — the model chooses | no — read and dry-run only |
Attaching an MCP client that has an LLM is what turns the same tool
into an AWS assistant: prose in, tool calls out. Note the direction —
the assistant gets fewer permissions than the operator, not more.
harness ask is the no-LLM middle ground: natural language in, but a
deterministic router with no ability to invent a command.
As a tool — the CLI
Twenty-five commands across eleven plugins. Installed above, it works immediately:
harness doctor # health: credentials, regions, plugins
harness account list # known accounts, all businesses
harness --business alpha account list # one business (global flag)
harness --all-accounts iam find-unused --days 90 # one sweep, every account
harness ec2 list-instances --state stopped --region eu-north-1
harness vpc audit --account production # IGW, NAT, NACL, flow logs
harness cost total --days 30 # Cost Explorer
harness console ec2 i-0abc1234 --region eu-north-1 # deep link, no navigationNatural language without an LLM — a deterministic router that can only
select commands which exist, and routes every mutation through
--dry-run first:
harness ask "show unused iam keys in prod"
# → harness iam find-unused --account prodGlobal flags, before or after the subcommand: --business,
--account, --all-accounts, --all-regions, --region,
--output table|json, --dry-run, --quiet, --verbose,
--profile, --role, --external-id, --refresh.
As a server — MCP
The same capability set, exposed for an AI client. One stdio process — no listener, no daemon, no port, no credentials in transit; the client spawns it as a child process.
harness serve-mcp # JSON-RPC on stdioOn a fresh machine, ./scripts/install.sh does the whole thing — a
dedicated virtual environment, the CLI on a path, the [mcp] extra, and a
config template (it never touches ~/.aws or an existing config).
--dry-run shows the plan first.
The MCP SDK is an optional extra: pip install 'cloud-harness-cli[mcp]'.
The pin excludes SDK 2.x, whose import path this code does not use.
Client registration — one line each:
Client | Registration |
Pi |
|
Hermes |
|
Claude Code |
|
VS Code |
|
A reasonable first exchange: "run doctor, then whoami". The client should report 24 tools. Configuration files, verification and a troubleshooting table are in docs/mcp-clients.md.
Tool surface (the 24 MCP tools)
Domain | Tools |
Identity and orientation |
|
Compute, storage, network |
|
Identity hygiene |
|
Serverless and edge |
|
Security posture |
|
Organization |
|
Backups, cost, inventory |
|
Simulation |
|
Safety model
The constraint that shaped the MCP surface: a boolean an LLM can set is not a safety boundary. Consequently the server is not given the ability to mutate.
Read and simulate only over MCP. Execution of changes happens in the CLI, behind
--yes. There is no MCP path to a real mutation.read_onlyis enforced once, in code (ensure_mutable), before any API call, and exits 2. Business- and account-level, with account overriding business.Result sets are capped at 50 rows over MCP so a sweep cannot consume a model's context.
Every action is attributable: CLI actions appear as
harness-<operator>in CloudTrail, MCP calls additionally land in the audit trail asharness:mcp.Least privilege and ExternalId on every AssumeRole — no confused-deputy exposure. Policies are in docs/harness-needed_aws-roles.md.
What it is not
Not a provisioning tool. No creates, no deletes, no drift management.
Not a multi-user service. One operator, one machine, per-account credentials.
Not a replacement for the console. It covers the routine questions — what exists, what it costs, what is exposed — not every edge case.
Related MCP server: aws-safe-mcp
Design
Multi-account by construction. Accounts come from the Organizations API or explicit config; nothing is inferred from the profile you happen to have loaded.
Multi-region with detection. Region scope per account is the intersection of configuration and what AWS reports as enabled, cached for 24 hours.
Every action attributable. AssumeRole carries an ExternalId and requests
SourceIdentity; where the organization blocks it, the harness falls back to session-name attribution rather than failing.Plugins, not monolith. Eleven service plugins behind a capability-based interface, loaded through entry points.
One capability set, two surfaces. The CLI and the MCP server call the same plugin methods; the MCP surface is the stricter subset.
Extending: a service is one file and one entry point
Every service is a plugin behind a deliberately small contract
(harness_plugins/base.py):
subclass
BasePlugin;declare
CAPABILITIES— a frozen dataclass naming the service, which verbs it supports (supports_read,supports_safe_ops), whether it is global rather than regional, and its rate limits as(api, transactions_per_second)pairs;return a Typer sub-app from
create_app();implement
list_resources()andget_resource().
Optional methods unlock more: describe, audit, safe_op,
dry_run_simulate, cost_info.
Registration is an entry point, not an edit to the core:
[project.entry-points."cloud_harness.plugins"]
my_service = "my_package.plugin:MyServicePlugin"Because discovery goes through importlib.metadata, a plugin can ship as
a separate installed package — no fork, no central registry file, no
import wiring. The harness finds it on the next run.
What a plugin inherits without writing any of it: account and region
fan-out through the thread pool, per-API rate limiting, credential
resolution and role assumption, --dry-run / --output / --quiet
plumbing, partial-failure reporting with meaningful exit codes, the
read_only choke point, and the audit trail.
One deliberate exception: the MCP surface is not generated from the plugin registry. Each tool is declared explicitly so the model-facing surface stays small, typed and reviewable. Adding a plugin gives you a CLI immediately; exposing it to a model is a separate, considered step.
Configuration
~/.config/cloud-harness/config.yaml — accounts, businesses, regions,
role ARNs, ExternalIds, read_only flags. Credentials never live in
this file: profiles, SSO or AssumeRole only.
harness init-db # local store: accounts, inventory snapshots, audit trailSee docs/architecture.md for internals and
docs/aws-reference.md for the AWS service
reference.
Capability matrix
Service | Read | Safe operation |
IAM | users, keys, MFA, policies | access-key rotation |
EC2 | instances, images | start / stop |
S3 | buckets, encryption, policy, ACL, PAB | — |
CloudFront | distributions | cache invalidation |
Lambda | functions, configuration | invocation |
VPC | VPCs, subnets, IGW/NAT, NACLs, routes, endpoints, flow logs | — |
Organizations | accounts, roots, OUs (management account) | — |
Cost Explorer | totals, per service | — |
Security | GuardDuty findings, Security Hub status | — |
Backup | vaults, plans, recovery points, jobs | start backup job |
Inventory | collected snapshots, diffs, search | — |
Read paths are safe to run anywhere. Safe operations default to
--dry-run; --yes executes, and read_only businesses refuse them.
Out of scope by design: provisioning, deletion, drift management (Terraform/CDK), and anything requiring a persistent daemon.
Credential handling
No credentials in configuration files — profiles, SSO or AssumeRole only.
Derived credentials are cached atomically at mode 0600, in a 0700 directory, written with
O_EXCLand no symlink following.Secrets are never written to stdout or logs; rotation writes the new key to a 0600 file and prints the path.
Per-account, per-region, per-API rate limiting (Cost Explorer is serialized at 0.5 TPS).
Documentation
Document | For |
every command, with live-verified output | |
wiring Pi, Hermes, Claude Code, VS Code | |
which interface, which model, data governance | |
IAM policies for each plugin, worked examples | |
internals, decisions, trade-offs | |
why this exists |
License
Apache License 2.0 — see LICENSE and NOTICE.
Not affiliated with, endorsed by, or sponsored by Amazon Web Services. AWS is a trademark of Amazon.com, Inc. This is an independent client that calls the AWS public APIs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only MCP server that answers questions about turva.dev from its published data. Five tools return JSON: the service catalog with prices, contact and operator details, engagement principles and dated agent-readiness and security evidence with verification links. Connect over Streamable HTTP. You need no API key. The server does not scan other websites or run audits.
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Read-only AI/LLM cost tools with current MCP discovery and attributable Registry transport.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only Model Context Protocol server that exposes over 60 AWS tools across services like EC2, S3, and IAM for AI agent interaction. It features multi-region support, resource caching, and audit logging to provide secure, AI-ready access to AWS infrastructure data.67 npmISC
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server for safe, structured investigation of AWS serverless resources, providing curated tools for tracing dependencies, permissions, and failures without exposing raw SDK access.45 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceA minimal, security-focused MCP gateway for connecting ChatGPT to AWS account data through explicit, read-only tools.MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that lets an LLM inspect an AWS account — list EC2 instances, S3 buckets, IAM users, and cost — with a structural guarantee against any mutations.MIT