# superuser MCP server

> Provides an AI agent with system administration capabilities including shell command execution and GitHub management through enterprise-grade guardrails.

- Repository: https://github.com/fitzyracing1/Super
- Page: https://hostedmcp.org/servers/fitzyracing1/super
- Transport: stdio
- Stars: 4
- Latest version: 0.1.1

## Install

### Claude Code

```sh
claude mcp add --env 'AI_DEFENSE_INSPECTION_API_KEY=<YOUR_AI_DEFENSE_INSPECTION_API_KEY>' --env 'DUO_CLIENT_SECRET=<YOUR_DUO_CLIENT_SECRET>' --env 'STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>' super -- uvx superuser
```

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

```json
{
  "mcpServers": {
    "super": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<YOUR_AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<YOUR_DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<YOUR_STRIPE_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "super": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<YOUR_AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<YOUR_DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<YOUR_STRIPE_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"super","type":"stdio","command":"uvx","args":["superuser"],"env":{"AI_DEFENSE_INSPECTION_API_KEY":"<YOUR_AI_DEFENSE_INSPECTION_API_KEY>","DUO_CLIENT_SECRET":"<YOUR_DUO_CLIENT_SECRET>","STRIPE_API_KEY":"<YOUR_STRIPE_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "super": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<YOUR_AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<YOUR_DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<YOUR_STRIPE_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add super --env 'AI_DEFENSE_INSPECTION_API_KEY=<YOUR_AI_DEFENSE_INSPECTION_API_KEY>' --env 'DUO_CLIENT_SECRET=<YOUR_DUO_CLIENT_SECRET>' --env 'STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>' -- uvx superuser
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.super]
command = "uvx"
args = ["superuser"]

[mcp_servers.super.env]
AI_DEFENSE_INSPECTION_API_KEY = "<YOUR_AI_DEFENSE_INSPECTION_API_KEY>"
DUO_CLIENT_SECRET = "<YOUR_DUO_CLIENT_SECRET>"
STRIPE_API_KEY = "<YOUR_STRIPE_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'AI_DEFENSE_INSPECTION_API_KEY=<YOUR_AI_DEFENSE_INSPECTION_API_KEY>' -e 'DUO_CLIENT_SECRET=<YOUR_DUO_CLIENT_SECRET>' -e 'STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>' super uvx -- superuser
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "super": {
      "command": "uvx",
      "args": [
        "superuser"
      ],
      "env": {
        "AI_DEFENSE_INSPECTION_API_KEY": "<YOUR_AI_DEFENSE_INSPECTION_API_KEY>",
        "DUO_CLIENT_SECRET": "<YOUR_DUO_CLIENT_SECRET>",
        "STRIPE_API_KEY": "<YOUR_STRIPE_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AI_DEFENSE_INSPECTION_API_KEY` | no | yes | Cisco AI Defense Inspection API key for runtime tool-call/response inspection. |
| `DUO_CLIENT_SECRET` | no | yes | Cisco Duo OAuth client secret. |
| `STRIPE_API_KEY` | no | yes | Stripe secret API key for usage-based (metered) billing. |
| `AI_DEFENSE_MODE` | no | no |  |
| `DUO_CLIENT_ID` | no | no | Cisco Duo OAuth client ID for the agent's non-human identity. |
| `DUO_TOKEN_URL` | no | no | Cisco Duo OAuth 2.1 token endpoint (client-credentials) for per-tool-call authorization. |
| `SUPERUSER_APPROVAL_AT` | no | no | Minimum risk level that triggers the human-approval gate: LOW, MEDIUM, HIGH, or CRITICAL. |
| `SUPERUSER_HUMAN_OWNER` | no | no | Human accountable for the agent's actions (recorded in every audit entry). |

## Tools (8)

- `system_status`
- `disk_usage`
- `list_processes`
- `run_command`
- `github_get_repo`
- `github_list_issues`
- `github_create_issue_comment`
- `security_status`

## FAQ

### What safety measures are included in the superuser agent?

The agent uses a dangerous-command denylist, a human-approval gate for risky operations, least-privilege GitHub access, an append-only audit log, and Cisco AI Defense runtime inspection.

### How does the approval gate work?

Any operation categorized at or above the specified risk threshold (defaulting to MEDIUM) requires an explicit confirmation from a human.

### Can I use this for billing purposes?

Yes, the agent supports usage-based billing via Stripe, allowing successful tool calls to be metered and sold per-action.

### What happens if Cisco AI Defense is not configured?

The agent will still run, but results will be explicitly annotated as unprotected.
