Skip to content
MCP server

Superuser

Permission-gated sysadmin MCP server with approval gates and an audit log

Runs locallyStatus and history
Install
Platforms
CLI, Linux, macOS
Runs
Locally
Version
0.1.1
Listing updated
today

Similar MCP servers

About Superuser

Superuser is an MCP server for security. It runs locally on your machine and is started by your AI client.

Superuser hands an AI client real shell and system powers on the host, but routes every call through a single guard. In order, the guard asks Cisco AI Defense to inspect the call, asks Cisco Duo for per-tool authorization, requires explicit human confirmation at or above a configurable risk level, runs the operation, inspects the response for leakage, optionally meters it through Stripe, and writes an audit entry naming the human owner.

GitHub access is least-privilege: with no token or an empty repository allowlist there is no access, and writes need an extra opt-in. The README notes that the command denylist is only a backstop, with inspection and approvals as the main controls. If the Cisco SDK or keys are missing it still runs, but marks results as unprotected.

It installs from PyPI and runs over stdio, so it suits teams who want sysadmin automation with accountability.

Install

Run in a terminal

claude mcp add superuser --env AI_DEFENSE_INSPECTION_API_KEY='<AI_DEFENSE_INSPECTION_API_KEY>' --env DUO_CLIENT_SECRET='<DUO_CLIENT_SECRET>' --env STRIPE_API_KEY='<STRIPE_API_KEY>' -- uvx superuser

Add to claude_desktop_config.json

{
  "mcpServers": {
    "superuser": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<STRIPE_API_KEY>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "superuser": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<STRIPE_API_KEY>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "superuser": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<STRIPE_API_KEY>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "superuser": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<STRIPE_API_KEY>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "superuser": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<STRIPE_API_KEY>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • SUPERUSER_HUMAN_OWNERHuman accountable for the agent's actions (recorded in every audit entry).
  • SUPERUSER_APPROVAL_ATMinimum risk level that triggers the human-approval gate: LOW, MEDIUM, HIGH, or CRITICAL.
  • AI_DEFENSE_INSPECTION_API_KEYCisco AI Defense Inspection API key for runtime tool-call/response inspection.
  • DUO_TOKEN_URLCisco Duo OAuth 2.1 token endpoint (client-credentials) for per-tool-call authorization.
  • DUO_CLIENT_IDCisco Duo OAuth client ID for the agent's non-human identity.
  • DUO_CLIENT_SECRETCisco Duo OAuth client secret.
  • STRIPE_API_KEYStripe secret API key for usage-based (metered) billing.

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

system_status
Reports host, CPU, memory and uptime (low risk).
disk_usage
Shows per-partition disk usage.
list_processes
Lists top processes by memory or CPU.
run_command
Runs a shell command with denylist, approval and audit.
github_get_repo
Fetches metadata for an allowlisted repository.
github_list_issues
Lists issues for an allowlisted repository.
github_create_issue_comment
Posts an issue comment; needs approval and write opt-in.
security_status
Reports the active guardrail configuration.

What it does

Risk-based approval gate
Operations at or above a set risk level need confirm=true from a human.
Cisco AI Defense inspection
Tool calls and responses are inspected, in enforce or monitor mode.
Duo authorization
Each call is authorized per policy through Cisco Duo non-human identity.
Append-only audit log
Records human owner, agent, tool, action and outcome.
Allowlisted GitHub access
Reads repos and issues only for allowlisted repositories; comments need write opt-in.
Stripe metering
Successful calls can emit meter events for usage-based billing.

Good for

  • Let an assistant check CPU, memory and disk on a server with an audit trail
  • Run shell commands only after a human approves risky ones
  • Triage issues in a fixed set of GitHub repositories
  • Prototype governed agent access for a security review

Pricing

Pricing unknown

Licence and pricing not stated; optional Cisco and Stripe services have their own terms

Superuser FAQ

What tools does it expose?

system_status, disk_usage, list_processes, run_command, github_get_repo, github_list_issues, github_create_issue_comment and security_status.

What does it need to run?

Python 3.10 or newer; install with pip or run with uvx. Cisco and Stripe features need the optional extras and credentials.

What happens without Cisco keys?

It still runs, but every result is flagged as unprotected.

Does it fail closed?

In enforce mode, inspection and authorization errors block the call; GitHub access also fails closed without a token and allowlist.

How do I add Superuser to Claude Code?

Run this command in your terminal: claude mcp add superuser --env AI_DEFENSE_INSPECTION_API_KEY='<AI_DEFENSE_INSPECTION_API_KEY>' --env DUO_CLIENT_SECRET='<DUO_CLIENT_SECRET>' --env STRIPE_API_KEY='<STRIPE_API_KEY>' -- uvx superuser

What are the best alternatives to Superuser?

The closest alternatives to Superuser are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers