minio-aiops
A governed MinIO AI-ops MCP server that provides read-only diagnostics plus audited, largely reversible writes across storage health, capacity, exposure, IAM, and WORM object lock.
Health & overview:
health_live,health_ready,health_cluster,cluster_status, andfleet_overviewfor liveness, readiness, write-quorum health, and a one-shot deployment summary.Capacity analysis:
capacity_rcafor ranked cause/action findings on filling storage, offline drives, hotspots, and imbalance, plususage_by_bucketfor per-bucket bytes/objects.Healing & drives:
healing_healthfor heal backlog and erasure-set write-quorum risk,drive_status, andnode_status.Exposure & ILM audits:
bucket_exposure_auditranks anonymous-read/write, encryption, versioning, and lifecycle risks;lifecycle_gap_analysisfinds noncurrent-expiry, multipart, and no-lifecycle gaps with reclaimable estimates.Bucket inspection: list buckets, full bucket config, policy, lifecycle, versioning, quota, object listing, incomplete multipart uploads, and admin
server_info.IAM inspection:
iam_users,iam_groups,iam_policies, anddiagnose_iam_exposurefor admin sprawl and unusable accounts.Object lock/WORM:
bucket_lock_config,object_lock_status, anddiagnose_retention_gapsfor retention, legal hold, and lock/versioning contradictions.Guarded writes: set/delete bucket policy, versioning, lifecycle, quota, empty-only bucket delete, abort old multipart uploads, create buckets (including object-lock), manage IAM users/policies, default retention, legal hold, and irreversible object retention with explicit guards.
Undo support:
undo_listandundo_applyreplay recorded inverse operations for reversible writes.Governance: every call is audited with risk tiers and outcome summaries, credentials are stored encrypted, budget/runaway guards apply, and destructive actions support dry-run.
Provides tools for managing and monitoring MinIO object storage, including capacity RCA, bucket exposure audits, lifecycle gap analysis, healing health, bucket and object operations, IAM, and governed writes with undo support.
MinIO AIops
Audit availability: Real writes require a committed
pendingaudit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by MinIO, Inc. or any storage vendor. Product and trademark names belong to their owners. MIT licensed.
Governed AI-ops for MinIO object storage — for the homelab and small/medium
self-hosted deployments where MinIO actually lives. Talks to the S3 API
(official minio SDK, SigV4), the admin API (bucket quota, server info),
the unauthenticated health endpoints (/minio/health/live|ready|cluster),
and the cluster metrics endpoint (/minio/v2/metrics/cluster, bearer-token
or public auth) — with a built-in governance harness: a unified audit log,
a token/runaway budget guard, undo-token recording, and a descriptive risk
tier on every audit row. Self-contained: no external skill-family dependency.
What it does
Four flagship analyses, plus the guarded reads and writes around them:
capacity_rca— capacity vs used, offline drives/nodes, per-drive hotspots and imbalance → each finding as cause + suggested action (nearfull/full thresholds are named constants, not magic).bucket_exposure_audit— every bucket scored and ranked for anonymous/public policy statements (read and, far worse, write), missing default encryption, versioning off, no lifecycle.lifecycle_gap_analysis— the storage ILM should be reclaiming but isn't: versioned buckets with no noncurrent expiry (old bytes accrue forever), incomplete multipart uploads with no abort rule (invisible space), large buckets with no lifecycle — with a clearly-labelled reclaimable estimate.healing_health— heal backlog and per-erasure-set write-quorum risk: how many more drive failures each set can tolerate, which sets are healing, where heal errors are piling up.Governed writes. Bucket policy / versioning / lifecycle / quota changes capture the real prior state and record an undo descriptor;
bucket_deleteis refused unless the bucket is verifiably empty (including versions and delete markers) andremove_incomplete_uploadsonly touches uploads older than a safety window.
Related MCP server: observability-aiops
What works
CLI (
minio-aiops ...):init,overview,doctor,health check/status,capacity rca/usage,heal status/drives/nodes,bucket ls/info/objects/audit/ilm-gap/uploadsplus guarded writes (bucket versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete),secret set/list/rm/migrate/rotate-password,mcp. Destructive commands take--dry-runand double-confirm.MCP server (
minio-aiops mcporminio-aiops-mcp): the full 48 tools (29 read, 19 write), every one wrapped with the bundled@governed_toolharness. The CLI is a convenience subset; the MCP surface is the whole tool. CLI writes delegate to the same governed functions, so they are audited identically.Encrypted credentials: the secret key lives in an encrypted store
~/.minio-aiops/secrets.enc(Fernet + scrypt) — never plaintext on disk. Unlock with a master password fromMINIO_AIOPS_MASTER_PASSWORD(MCP/CI) or an interactive prompt (CLI).Metrics auth, both modes: servers running
MINIO_PROMETHEUS_AUTH_TYPE=publicare scraped directly; for the default (jwt) mode the bearer token is derived from the stored credentials — no extra secret to manage.Reversibility: reversible writes capture prior state and record an inverse undo descriptor (prior policy JSON, prior lifecycle XML, prior versioning state, prior quota).
Capability matrix (48 MCP tools)
Group | Tools | Count | R/W |
Health |
| 5 | read |
Capacity |
| 2 | read |
Healing |
| 3 | read |
Exposure / ILM |
| 2 | read |
Buckets |
| 9 | read |
Writes |
| 6 | write |
| 2 | write | |
Object lock (WORM) |
| 3 | read |
| 4 | write | |
| 1 | write | |
IAM |
| 4 | read |
| 4 | write | |
| 1 | write | |
Undo |
| 2 | read + replay |
Totals: 48 tools — 29 read (incl. undo_list), 19 write (incl. undo_apply).
What this tool does, and does not, decide
It delivers MinIO object-storage operations — reads and writes — accurately and efficiently, and records every one of them. It does not decide whether a write is allowed to happen. That is the agent's judgement, or the permission of the access key you connect it with: give the key a read-only IAM policy and the writes fail at the server — the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.minio-aiops/audit.db,
and reversible writes still capture their real prior state and record an inverse
undo descriptor.
Each tool declares a
risk_level, kept in agreement with its[READ]/[WRITE]documentation tag by a test, and carried into the audit row as a descriptive tier — so a reviewer can see at a glance that a row was a high-risk delete. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
Quick start
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install minio-aiops@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with minio-aiops init — see below.
As an OpenClaw plugin
The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:
openclaw plugins install clawhub:@zw008/minio-aiops
openclaw skills info minio-aiops # expect: Visible to model: yesRestart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
As a CLI or standalone MCP server
uv tool install minio-aiops # or: pipx install minio-aiops
minio-aiops init # wizard: endpoint + access key; secret key stored encrypted
minio-aiops doctor # live/ready + S3 auth + metrics reachability
minio-aiops overview # health + capacity headline + exposure headline
minio-aiops capacity rca # why is storage filling up, and what to do
minio-aiops bucket audit # ranked bucket-exposure findingsRun as an MCP server (stdio):
export MINIO_AIOPS_MASTER_PASSWORD=... # unlock secrets non-interactively
minio-aiops-mcpWhere that password then lives: an exported variable is readable by every process this shell starts and is recorded by shell history. On a shared or long-lived host, prefer the interactive prompt, or inject it from a secret manager for the life of the one command that needs it.
MCP client config
{
"mcpServers": {
"minio-aiops": {
"command": "uvx",
"args": ["--from", "minio-aiops", "minio-aiops-mcp"],
"env": { "MINIO_AIOPS_MASTER_PASSWORD": "your-master-password" }
}
}
}Env-block caveat: MCP clients launch the server without a TTY and without your shell profile, so the master password cannot be prompted for and an
exportin~/.zshrcis not seen — it must be passed in the client'senvblock (or the client process's environment) as above. Everything else (targets, TLS, region, metrics mode) comes from~/.minio-aiops/config.yamlwritten byminio-aiops init.
Configuration
~/.minio-aiops/config.yaml (non-secret connection details only):
targets:
- name: lab1
host: 192.0.2.10
port: 9000
access_key: minio-ops # identifies the account; NOT the secret
secure: true # https (false for plain-http labs)
verify_ssl: true # false for self-signed lab certs
region: "" # optional
metrics_public: false # true when MINIO_PROMETHEUS_AUTH_TYPE=publicThe secret key is stored with minio-aiops secret set lab1 (encrypted; a
legacy MINIO_LAB1_SECRET_KEY env var is honoured as a fallback with a
migration warning).
Governance
Every MCP tool passes through the bundled @governed_tool harness:
Audit — every call (params, outcome summary, status, duration, risk tier, and any
MINIO_AUDIT_APPROVED_BY/MINIO_AUDIT_RATIONALEannotations) is logged to~/.minio-aiops/audit.db(relocatable viaMINIO_AIOPS_HOME).Budget / runaway guard — token and call budgets trip a circuit breaker. A safety backstop, not authorization.
Risk-tier labelling — each tool's declared
risk_levelis recorded on the audit row as a descriptive tier (bucket_deleteis high). It is a label for the reviewer, not a gate: there is no read-only switch, policy file, or approval gate, andMINIO_AUDIT_APPROVED_BY/MINIO_AUDIT_RATIONALEare optional annotations recorded when set, never required.Undo recording — reversible writes record an inverse descriptor built from the captured prior state.
Supported scope & limitations
Deployments: any reasonably current MinIO server (single-node or distributed/erasure-coded) reachable over its S3 port. Admin features (quota,
server_info) need admin-capable keys. Generic S3 services are not a target: the health/metrics/admin surfaces used here are MinIO-specific.Metrics: the capacity/healing RCAs read the v2 cluster metrics endpoint; both
publicand bearer-token (default) auth modes are supported.Incomplete-upload listing uses the SDK's core ListMultipartUploads call (the public alias was removed from the SDK); it is exercised in tests and documented in
connection.py.Verification status. Live-verified against a real single-node MinIO server (2026-07-19): connectivity, the reads, the exposure audit (it correctly scored an anonymously-writable bucket
highand namedPUBLIC_WRITE_POLICY), and the governance loop (realset_versioning→ undo restoring it toSuspended, the correct S3 inverse). Distributed / multi-node MinIO is still unverified — healing was never exercised against a real degraded drive or erasure set — as are lifecycle/quota writes and TLS endpoints. See docs/VERIFICATION.md;minio-aiops doctoris the fastest live check.
Missing a capability?
Site replication status, IAM policy authoring (creating and editing policy documents — attachment is supported), group membership writes, tiering to remote storage — not here yet. Open an issue or send a PR — feedback and contributions are welcome.
Available Tools
48 toolsattach_user_policyADestructive
[WRITE][risk=medium] Attach canned policies to a user. Reversible → detach.
Refused for this tool's own credential: MinIO's canned policies replace what a credential may do rather than only adding to it, so this can silently narrow the tool's own access.
Args: access_key: The user's access key (from iam_users). policies: Policy names to attach (from iam_policies). dry_run: If True, preview without attaching. target: MinIO target name from config; omit for the default.
Inputs: policies (required), access_key (required), target, dry_run.
bucket_createADestructive
[WRITE][risk=medium] Create a bucket, optionally WORM-capable. Reversible.
object_lock=True is the ONLY way to get object lock: S3 accepts the flag at bucket creation and has no call that enables it later. The server force-enables versioning as a consequence; the result reports what it observed rather than what was assumed.
Undo deletes the bucket, and only while it is still empty.
Args: bucket_name: New bucket name (3-63 chars, lowercase/digits/dots/hyphens). object_lock: Enable object lock (WORM). Cannot be changed afterwards. dry_run: If True, preview without creating. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run, object_lock.
bucket_deleteADestructive
[WRITE][risk=high] Delete a bucket — refused unless verifiably empty. Irreversible.
Pass dry_run=True to preview. The emptiness check includes noncurrent versions and delete markers; this tool never mass-deletes data to force a bucket empty.
Args: bucket_name: Bucket name (from bucket_ls). dry_run: If True, preview (including the emptiness check) without deleting. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run.
bucket_exposure_auditARead-only
[READ] Ranked bucket-exposure findings (riskiest first), cause + action.
Scores every bucket for anonymous/public policy statements (read and write), missing default encryption, versioning off, and no lifecycle — the fastest answer to "is anything in my object storage exposed?".
Args: limit: Maximum buckets to audit (default 100). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
bucket_infoARead-only
[READ] One bucket's full config: policy, versioning, lifecycle, encryption, quota, tags.
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
bucket_lifecycle_getARead-only
[READ] The bucket's lifecycle rules (null when no lifecycle is set).
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
bucket_lock_configARead-only
[READ][risk=low] Object-lock (WORM) state of one bucket.
Distinguishes the two absences that look alike and mean different things: objectLockEnabled=false (lock was never enabled and cannot be enabled on an existing bucket) versus objectLockEnabled=true with defaultRetention=null (WORM is available, but an upload that omits its own retention header is retained for nothing).
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
bucket_lsARead-only
[READ] Buckets (name + creation time) in a truncation-aware envelope.
Returns {"buckets": [...], "returned": N, "limit": L, "truncated": bool}. When "truncated" is true there are MORE buckets than shown — re-run with a higher limit rather than reporting the list as complete.
Args: limit: Maximum buckets to return (default 500). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
bucket_policy_getARead-only
[READ] The bucket's policy JSON (verbatim) + anonymous-access summary.
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
bucket_quota_getARead-only
[READ] The bucket's hard quota (0 = unlimited). Needs admin credentials.
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
bucket_versioning_getARead-only
[READ] The bucket's versioning state: Enabled / Suspended / Off.
Args: bucket_name: Bucket name (from bucket_ls). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target.
capacity_rcaARead-only
[READ] Capacity & usage RCA: cause + suggested action per finding.
Call this first on any "storage is filling up / writes are failing" question — it folds capacity vs used, offline drives/nodes, per-drive hotspots, and imbalance into ranked findings with what to do next.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
clear_default_retentionADestructive
[WRITE][risk=medium] Remove the DEFAULT retention rule. Reversible → prior rule.
Clears the rule only. Object lock stays enabled on the bucket (S3 has no call that disables it) and objects already carrying retention keep it, so this makes future uploads unprotected and changes nothing already stored.
Args: bucket_name: Bucket name (must have object lock enabled). dry_run: If True, preview without clearing. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run.
cluster_statusBRead-only
[READ] Dashboard-header summary: nodes, drives, capacity, buckets, objects.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
create_userADestructive
[WRITE][risk=medium] Create or reset an IAM user. Reversible → remove.
The secret is redacted in the audit row and is NOT returned: the harness stores a result verbatim, so echoing it would persist a live credential in plaintext. A new user has no policy and can do nothing until one is attached.
MinIO treats this as an upsert — an existing access key has its secret REPLACED, and no undo can restore the old one, so the undo is recorded only for a genuinely new account.
Args: access_key: The new user's access key (3-128 chars, letters/digits/._=+-). secret_key: The new user's secret (8+ chars). Redacted in the audit log. dry_run: If True, preview without creating. target: MinIO target name from config; omit for the default.
Inputs: access_key (required), secret_key (required), target, dry_run.
delete_bucket_policyADestructive
[WRITE][risk=medium] Remove the bucket policy (back to private/default).
Reversible → the prior policy JSON is captured and re-applied on undo.
Args: bucket_name: Bucket name (from bucket_ls). dry_run: If True, preview without removing. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run.
delete_lifecycleADestructive
[WRITE][risk=medium] Remove all lifecycle rules. Reversible → prior config.
Args: bucket_name: Bucket name (from bucket_ls). dry_run: If True, preview without removing. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run.
detach_user_policyADestructive
[WRITE][risk=medium] Detach canned policies from a user. Reversible → attach.
Refused for this tool's own credential: the account keeps authenticating and loses exactly the rights the undo would need to put them back.
Args: access_key: The user's access key (from iam_users). policies: Policy names to detach (from iam_users). dry_run: If True, preview without detaching. target: MinIO target name from config; omit for the default.
Inputs: policies (required), access_key (required), target, dry_run.
diagnose_iam_exposureARead-only
[READ][risk=low] Ranked IAM findings: admin sprawl and unusable accounts.
Resolves group-inherited policies first, so a correctly group-managed user is not reported as having no permissions. Findings: NO_EFFECTIVE_POLICY (MinIO denies by default, so the account can do nothing — a broken account that looks identical to a working one in any name-and-status listing), FULL_ADMIN_POLICY, BROAD_DATA_POLICY, DISABLED_BUT_PRIVILEGED. Sorted worst-first with rank.
Args: limit: Maximum findings to return (envelope reports truncation). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
diagnose_retention_gapsARead-only
[READ][risk=low] WORM/retention gaps across every bucket, worst-first.
Finds the contradictions rather than a house style: lock enabled with no default retention (protects nothing), a lifecycle expiry that retention outlives (the rule can never delete and the capacity never returns — both day counts reported), object lock on a bucket whose versioning is not active, and the mode choice with its consequence spelled out.
Buckets whose probes fail are listed in bucketErrors rather than skipped: a clean findings list does not mean those buckets are clean.
Args: limit: Maximum findings to return (envelope reports truncation). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
drive_statusARead-only
[READ] Per-drive rows (server, drive, used ratio), fullest first.
Returns {"drives": [...], "returned": N, "error": str | None}. A non-null "error" means the metrics scrape failed — that is NOT the same as a server with no drives, so do not report an empty list as "healthy, nothing to see".
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
fleet_overviewARead-only
[READ] One-shot deployment overview: health + capacity + exposure headline.
Call this first on any broad "how is my object storage doing" question.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
healing_healthARead-only
[READ] Healing backlog + erasure-set write-quorum risk, cause + action.
Answers "how many more drive failures can I take?": per-erasure-set online drives vs write quorum (remaining failure tolerance), drives currently healing, heal backlog/errors — each risk as a plain-language finding.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
health_clusterARead-only
[READ] Cluster write-quorum health (/minio/health/cluster; 503 = degraded).
Combined with liveness/readiness in one structured answer plus an overall 'healthy' verdict.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
health_liveARead-only
[READ] Node liveness probe (unauthenticated /minio/health/live).
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
health_readyARead-only
[READ] Node readiness probe (unauthenticated /minio/health/ready).
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
iam_groupsARead-only
[READ][risk=low] IAM groups with members and attached policies.
Groups whose read fails are listed in groupErrors rather than dropped.
Args: limit: Maximum groups to return (envelope reports truncation). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
iam_policiesARead-only
[READ][risk=low] Canned policy names defined on the deployment.
Args: limit: Maximum policy names to return (envelope reports truncation). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
iam_usersARead-only
[READ][risk=low] IAM users with status, attached policies, group membership.
An empty list carries a note: the root credential (MINIO_ROOT_USER) is not an IAM user and never appears, so a root-only deployment legitimately reports no users — not a failed probe.
Args: limit: Maximum users to return (envelope reports truncation). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
incomplete_uploads_lsARead-only
[READ] In-flight/abandoned multipart uploads in a truncation-aware envelope.
Returns {"uploads": [...], "returned": N, "limit": L, "truncated": bool}. Each row: objectName, uploadId, initiated time (null when the source gave none). When "truncated" is true, re-run with a higher limit.
Args: bucket_name: Bucket name (from bucket_ls). prefix: Key prefix filter; empty for the whole bucket. limit: Maximum uploads to return (default 200). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), limit, prefix, target.
lifecycle_gap_analysisARead-only
[READ] ILM gaps per bucket + reclaimable estimate, cause + action.
Finds versioned buckets with no noncurrent expiry (old bytes accrue forever), incomplete multipart uploads with no abort rule (invisible space), and large buckets with no lifecycle at all.
Args: limit: Maximum buckets to analyze (default 100). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
node_statusARead-only
[READ] Node-level view: online/offline nodes + per-node drive counts.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
object_lock_statusARead-only
[READ][risk=low] Retention + legal hold for one object version.
Reports whether the version is deletable right now and what blocks it. Retention and legal hold stack independently: lifting the hold does not help while retention runs, and a lapsed retention does not help while the hold is on.
Args: bucket_name: Bucket name (from bucket_ls). object_name: Object key (from bucket_objects). version_id: Specific version; omit for the current version. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), object_name (required), target, version_id.
object_lsARead-only
[READ] Objects under prefix in a truncation-aware envelope (never a full walk).
Returns {"objects": [...], "returned": N, "limit": L, "truncated": bool}. A bucket can hold millions of keys, so "truncated" being true is the normal case — say so and re-run with a higher limit or a narrower prefix instead of treating the page as the whole bucket. "lastModified" and "versionId" are null when the source had no value.
Args: bucket_name: Bucket name (from bucket_ls). prefix: Key prefix filter; empty for the whole bucket. limit: Maximum objects to return (default 100, max 1000). target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), limit, prefix, target.
remove_incomplete_uploadsADestructive
[WRITE][risk=medium] Abort abandoned multipart uploads (reclaims their parts).
priorState records the count and a sample; the parts themselves are unrecoverable once aborted — no undo. Only uploads at least older_than_days old are touched (default 7), protecting in-flight uploads.
Args: bucket_name: Bucket name (from bucket_ls). older_than_days: Only abort uploads at least this old (0 = all). dry_run: If True, preview the matching uploads without aborting. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), target, dry_run, older_than_days.
remove_userADestructive
[WRITE][risk=high] Delete an IAM user. IRREVERSIBLE — no undo is recorded.
MinIO keeps no recoverable copy of the secret, so the account cannot be restored, only recreated with a secret supplied again. priorState captures the status and policy attachments so the same rights can be rebuilt. Refused when it targets this tool's own credential.
Args: access_key: The user's access key (from iam_users). dry_run: If True, run the guards and report without deleting. target: MinIO target name from config; omit for the default.
Inputs: access_key (required), target, dry_run.
server_infoBRead-only
[READ] Admin server info: mode, servers/pools summary. Needs admin credentials.
Args: target: MinIO target name from config; omit for the default.
Inputs: target.
set_bucket_policyADestructive
[WRITE][risk=medium] Replace the bucket policy. Reversible → prior policy JSON.
An anonymous-Allow policy makes the bucket public — check bucket_exposure_audit after changing policies.
Refuses a policy whose explicit Deny on s3:PutBucketPolicy covers this tool's own access key: an explicit Deny beats every Allow, so the undo that replays the prior policy would itself be denied. Enforced under dry_run too.
Args: bucket_name: Bucket name (from bucket_ls). policy_json: Full policy document as a JSON string (must contain 'Statement'). dry_run: If True, preview without applying. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), policy_json (required), target, dry_run.
set_bucket_quotaADestructive
[WRITE][risk=medium] Set (>0) or clear (0) the bucket hard quota. Reversible.
Needs admin-capable credentials (admin API).
Args: bucket_name: Bucket name (from bucket_ls). size_bytes: New hard quota in bytes; 0 clears the quota. dry_run: If True, preview without changing the quota. target: MinIO target name from config; omit for the default.
Inputs: size_bytes (required), bucket_name (required), target, dry_run.
set_default_retentionADestructive
[WRITE][risk=high] Set the bucket's DEFAULT retention. Reversible → prior rule.
Applies to objects written from now on; objects already stored are untouched. Undo restores the prior rule — but objects written while this rule was in force keep the retention they were given, and COMPLIANCE retention on them cannot be shortened by anyone afterwards.
Refused (under dry_run too) when the bucket has no object lock, since the rule would have nothing to attach to.
Args: bucket_name: Bucket name (must already have object lock enabled). mode: "GOVERNANCE" (an admin with bypass permission can lift it) or "COMPLIANCE" (nobody can lift it before the date). days: Retention duration in days. Pass exactly one of days/years. years: Retention duration in years. Pass exactly one of days/years. dry_run: If True, preview without applying. target: MinIO target name from config; omit for the default.
Inputs: mode (required), bucket_name (required), days, years, +2 more.
set_legal_holdADestructive
[WRITE][risk=medium] Turn a legal hold on/off. Reversible → prior hold state.
A legal hold blocks deletion with no date attached and is lifted by turning it off — the one WORM control that is reversible by design. It stacks with retention: lifting the hold does not make an object deletable while its retention still runs.
Args: bucket_name: Bucket name (must have object lock enabled). object_name: Object key (from bucket_objects). hold_on: True places the hold, False lifts it. version_id: Specific version; omit for the current version. dry_run: If True, preview (reading the current hold) without changing it. target: MinIO target name from config; omit for the default.
Inputs: hold_on (required), bucket_name (required), object_name (required), target, +2 more.
set_lifecycleADestructive
[WRITE][risk=medium] Replace the bucket lifecycle. Reversible → prior config.
Pass the day-count knobs (rules are built for you: current-version expiry, noncurrent-version expiry), or lifecycle_xml to apply a configuration verbatim (used by undo restores). REPLACES any existing rules — the prior config is captured for undo.
Aborting abandoned multipart uploads is NOT available here: MinIO refuses a lifecycle rule whose only action is that, and drops the action when it is combined with an expiration. Use remove_incomplete_uploads instead.
The undo restores the RULE, not the data: objects the rule expires before you undo are deleted, and putting the prior configuration back does not bring them back.
Args: bucket_name: Bucket name (from bucket_ls). expire_days: Expire current objects after N days. noncurrent_expire_days: Expire noncurrent versions after N days. prefix: Optional key prefix the rules apply to (empty = whole bucket). lifecycle_xml: Full lifecycle configuration XML to apply verbatim. dry_run: If True, preview without applying. target: MinIO target name from config; omit for the default.
Inputs: bucket_name (required), prefix, target, dry_run, +3 more.
set_object_retentionADestructive
[WRITE][risk=critical] Put retention on one object version. NO UNDO EXISTS.
This is extend-only and irreversible through this tool, not by policy but by construction: S3 refuses to shorten or remove retention without the x-amz-bypass-governance-retention header, and the minio SDK never sends it. COMPLIANCE mode cannot be shortened by any credential at all — not root — until the date passes, and the storage cannot be reclaimed before then.
No undo token is recorded. Calls that would shorten or downgrade retention already in force are refused, and COMPLIANCE requires acknowledge_irreversible=True. Both refusals fire under dry_run.
Args:
bucket_name: Bucket name (must have object lock enabled).
object_name: Object key (from bucket_objects).
mode: "GOVERNANCE" (liftable out of band with mc retention clear by a
holder of s3:BypassGovernanceRetention — note that command has no
--bypass flag) or "COMPLIANCE" (liftable by nobody before the date,
root included).
days: Retain for this many days from now.
version_id: Specific version; omit for the current version.
acknowledge_irreversible: Required True for COMPLIANCE mode.
dry_run: If True, run every guard and report the before-state without writing.
target: MinIO target name from config; omit for the default.
Inputs: days (required), mode (required), bucket_name (required), object_name (required), +4 more.
set_user_statusADestructive
[WRITE][risk=medium] Enable or disable an IAM user. Reversible → prior status.
Refused when it targets the access key this tool authenticates with: the change would take effect and then reject every following call, the undo included. Enforced under dry_run too.
Args: access_key: The user's access key (from iam_users). enabled: True enables the account, False disables it. dry_run: If True, preview without changing the status. target: MinIO target name from config; omit for the default.
Inputs: enabled (required), access_key (required), target, dry_run.
set_versioningADestructive
[WRITE][risk=medium] Enable or suspend bucket versioning. Reversible → prior state.
Args: bucket_name: Bucket name (from bucket_ls). status: "Enabled" or "Suspended". dry_run: If True, preview without changing versioning. target: MinIO target name from config; omit for the default.
Inputs: status (required), bucket_name (required), target, dry_run.
undo_applyADestructive
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so it is audited under its own real risk tier there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an _undo_id in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
Inputs: undo_id (required), target, dry_run.
undo_listARead-only
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that undo_apply
would run, and a human note. Use the undoId with undo_apply.
Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}.
truncated is measured (one extra row is fetched), not guessed from a
length coincidence: when it is true there are MORE tokens than shown, so
re-run with a higher limit rather than reporting the list as complete.
Each entry carries effectVerified. False means the original write lost
its response, so the change it reverses is PROBABLE, not confirmed — check
the live state before applying, and do not report the result as a restore
of a state that may never have been reached.
Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.
Inputs: limit, target.
usage_by_bucketARead-only
[READ] Per-bucket usage (bytes + objects), biggest first, in an envelope.
Returns {"buckets": [...], "returned": N, "limit": L, "truncated": bool}.
When "truncated" is true, buckets outside the top limit were not shown —
do not present the list as the deployment's complete usage breakdown.
Args: limit: Maximum rows to return (default 25). target: MinIO target name from config; omit for the default.
Inputs: limit, target.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Many diagnostic tools overlap in the cluster-health/overview space (fleet_overview, cluster_status, server_info, capacity_rca, healing_health, drive_status), and bucket_info duplicates the per-config getters. The descriptions provide strong guidance, but the sheer number of similar-sounding health/audit tools creates selection friction.
All names are snake_case, but the verb pattern is mixed: noun_verb for reads (bucket_policy_get, bucket_delete, bucket_ls) and verb_noun for most writes (set_bucket_policy, create_user), with some bare nouns (bucket_info, iam_users). The grouping by prefix helps, but the convention is not uniform.
48 tools is far above the 3-15 sweet spot and exceeds the 25-tool threshold where a set is generally considered too large. While each tool maps to a distinct MinIO operation, the volume risks overwhelming an agent and hinders efficient selection.
The surface covers buckets, objects, IAM users, WORM/retention, health checks, and undo management well, but has notable gaps: no IAM group write operations (create/delete/add member/remove member), no object data-plane actions (delete/copy/tag), and no bucket tag/encryption write tools. These omissions will force workarounds for common admin tasks.
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Hosted remote MCP for protected account access, permissions, activity history and supported undo.
Capability-routed CLI/MCP: signed provenance exports, WCAG-validated themes, sovereign deploy modes.
Governed MCP workflow automation for MSPs and agencies: approvals, durable state, signed evidence.
Related MCP Servers
- AlicenseAqualityBmaintenanceGoverned MySQL + MariaDB DBA operations — slow-query, lock-wait/deadlock, replication, and fragmentation RCA, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.35MIT
- AlicenseAqualityBmaintenanceGoverned Prometheus + Grafana operations — firing-alert and scrape-target RCA, alert noise/flapping analysis, silences, and dashboards, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.39MIT
- AlicenseAqualityBmaintenanceGoverned SSO/IAM operations for Keycloak and Authentik — login-failure, stale-permission, client-config, and MFA RCA, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.29MIT
- AlicenseAqualityBmaintenanceGoverned CI/CD operations for self-hosted GitLab and Gitea — pipeline-failure, runner, artifact-bloat, and stale-branch RCA, with unbypassable audit logging (MCP + CLI), budget/runaway guards, dry-run, and undo/rollback.28MIT