Superuser
Permission-gated sysadmin MCP server with approval gates and an audit log
- 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 superuserAdd 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.


