# Superuser

> Superuser is an MCP server for security. Permission-gated sysadmin MCP server with approval gates and an audit log. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, Linux, macOS, Windows
- **Repository:** https://github.com/fitzyracing1/super
- **MCP Registry name:** io.github.fitzyracing1/superuser
- **Categories:** [security](https://ai-powered.com/categories/security), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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.

## 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.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/superuser
