Provides an AI agent with system administration capabilities including shell command execution and GitHub management through enterprise-grade guardrails.
Also known as fitzyracing1/Super, super
- Stars
- 4
- Tools
- 8
- Downloads, 30 days
- 277
- Latest version
- 0.1.1
- Last commit
- Nov 13, 2026
- License
- —
What is superuser MCP?
superuser provides an AI agent with system administration capabilities including shell command execution and GitHub management through enterprise-grade guardrails. It exposes 8 tools, such as system_status, disk_usage, list_processes.
Summary generated from the project's README
About superuser MCP server
Giving an AI agent system administration powers while maintaining enterprise security is the primary goal of this MCP server. It allows an agent to execute shell commands, monitor host status, and manage GitHub repositories through a permission-gated interface. Developers can use it locally via stdio transport with clients like Claude or Cursor to perform tasks ranging from checking disk usage to managing repository issues.
Security is managed through a multi-layered guardrail system. Every tool call undergoes inspection by Cisco AI Defense and authorization via Cisco Duo Agentic Identity. High-risk operations, such as running unallowlisted shell commands or writing to GitHub, require explicit human approval through a configurable threshold. The server also maintains an append-only audit log that tracks every action from the human owner to the specific tool outcome.
This server is designed for production environments that require accountability and monetization. It integrates with Stripe to enable usage-based billing by emitting meter events for successful tool calls. Users must configure environment variables for GitHub tokens, Duo credentials, and Stripe API keys to enable these advanced enterprise features.
What you can do with it
- 1Audit agent activityReview a detailed log of which human owner authorized which agent action.
Written from the project's README. Every use case is checked against a quote from it.
How to install superuser MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall superuser MCP in Claude Code
$ 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 superuserInstall superuser MCP in Cursor
~/.cursor/mcp.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>"
}
}
}
}Install superuser MCP in VS Code
.vscode/mcp.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>"
}
}
}
}Install superuser MCP in VS Code CLI
$ 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>"}}'Install superuser MCP in Claude Desktop
claude_desktop_config.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>"
}
}
}
}Install superuser MCP in Codex
$ 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 superuserInstall superuser MCP in Codex config.toml
~/.codex/config.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>"
Install superuser MCP in Gemini CLI
$ 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 -- superuserInstall superuser MCP in Gemini settings.json
~/.gemini/settings.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>"
}
}
}
}superuser MCP tools 8
Detected from the READMEsystem_statusdisk_usagelist_processesrun_commandgithub_get_repogithub_list_issuesgithub_create_issue_commentsecurity_status
| system_status | — | |
| disk_usage | — | |
| list_processes | — | |
| run_command | — | |
| github_get_repo | — | |
| github_list_issues | — | |
| github_create_issue_comment | — | |
| security_status | — |
Configuration
AI_DEFENSE_INSPECTION_API_KEYSecretCisco AI Defense Inspection API key for runtime tool-call/response inspection.
DUO_CLIENT_SECRETSecretCisco Duo OAuth client secret.
STRIPE_API_KEYSecretStripe secret API key for usage-based (metered) billing.
AI_DEFENSE_MODEDUO_CLIENT_IDCisco Duo OAuth client ID for the agent's non-human identity.
DUO_TOKEN_URLCisco Duo OAuth 2.1 token endpoint (client-credentials) for per-tool-call authorization.
SUPERUSER_APPROVAL_ATMinimum risk level that triggers the human-approval gate: LOW, MEDIUM, HIGH, or CRITICAL.
SUPERUSER_HUMAN_OWNERHuman accountable for the agent's actions (recorded in every audit entry).
| Name | Description | |
|---|---|---|
| AI_DEFENSE_INSPECTION_API_KEY | Cisco AI Defense Inspection API key for runtime tool-call/response inspection. | Secret |
| DUO_CLIENT_SECRET | Cisco Duo OAuth client secret. | Secret |
| STRIPE_API_KEY | Stripe secret API key for usage-based (metered) billing. | Secret |
| AI_DEFENSE_MODE | — | |
| DUO_CLIENT_ID | Cisco Duo OAuth client ID for the agent's non-human identity. | |
| DUO_TOKEN_URL | Cisco Duo OAuth 2.1 token endpoint (client-credentials) for per-tool-call authorization. | |
| SUPERUSER_APPROVAL_AT | Minimum risk level that triggers the human-approval gate: LOW, MEDIUM, HIGH, or CRITICAL. | |
| SUPERUSER_HUMAN_OWNER | Human accountable for the agent's actions (recorded in every audit entry). |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubSuper
A permission-gated superuser agent exposed over the Model Context Protocol (MCP). It gives an AI agent real system-administration powers on this machine — running shell commands, checking system state, and acting on GitHub — while wrapping every action in guardrails: 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 of every tool call and response.
The design goal is the version of a "superuser agent" you can actually ship: powerful, but safe, auditable, and compatible with enterprise guardrails.
Landing site: https://fitzyracing1.github.io/super-landing/ (source: fitzyracing1/super-landing). The previous Pages site in this repo is preserved at tag
site-v1/ branchsite-archive.
Why it's built this way
An agent that can do anything as root is a liability, not a product. Buyers
(and marketplace security reviews) expect scoping, approvals, and an audit
trail. So capabilities here always pass through a single choke point — the
Guard — which enforces, in order:
- Cisco AI Defense inspects the tool call (can block).
- Cisco Duo Agentic Identity authorizes the tool call per-policy (can block).
- Approval gate — anything at or above
approval_required_at(defaultMEDIUM) needs an explicitconfirm=truefrom a human. - The operation runs.
- Cisco AI Defense inspects the response before it is returned (catches data leakage).
- Stripe meters the successful call (best-effort; never blocks).
- The outcome is written to the audit log as
human owner -> agent -> tool -> action -> outcome.
This mirrors the enterprise model: your app owns scoping + approvals + local audit; Cisco AI Defense provides runtime threat inspection at the MCP layer; Cisco Duo Agentic Identity provides per-tool-call authorization tied to an accountable human owner; and Stripe turns metered tool calls into revenue.
Cisco Duo Agentic Identity (authorization)
Duo follows a "Duo decides, the gateway enforces" model. This agent registers as
a non-human identity, authenticates via the OAuth 2.1 client-credentials
grant (with an RFC 8707 resource indicator), and authorizes every tool call
either by matching the tool's required scope against what Duo granted, or by
calling an explicit Duo decision endpoint. Set DUO_ENABLED=true plus
DUO_TOKEN_URL / DUO_CLIENT_ID / DUO_CLIENT_SECRET (see .env.example). When
Duo is not configured, calls are allowed but flagged governed: false; in
enforce mode authorization errors fail closed.
Stripe usage-based billing (monetization)
Each authorized, successful tool call emits a Stripe meter event
(v2 billing meter events API), so the agent can be sold per-action. Configure a
meter in Stripe, then set STRIPE_ENABLED=true, STRIPE_API_KEY,
STRIPE_CUSTOMER_ID, and STRIPE_METER_EVENT_NAME. Per-tool weights let
higher-risk actions cost more. Billing is best-effort: metering failures are
logged and never block or fail the tool call (results are annotated
billed: true|false).
Tools
| Tool | Risk | Notes |
|---|---|---|
system_status |
LOW | Host, CPU, memory, uptime |
disk_usage |
LOW | Per-partition disk usage |
list_processes |
LOW | Top processes by memory/cpu |
run_command |
HIGH* | Shell command; denylist + approval + audit |
github_get_repo |
LOW | Repo metadata (allowlisted repos only) |
github_list_issues |
LOW | Issues for an allowlisted repo |
github_create_issue_comment |
HIGH | Write; needs approval + GITHUB_ALLOW_WRITES |
security_status |
— | Reports the active guardrail configuration |
* run_command is LOW risk only when its base command is in
command_allowlist; otherwise HIGH (requires confirm=true).
Install
Not yet on PyPI. Install straight from git:
pip install "superuser @ git+https://github.com/fitzyracing1/Super.git"
pip install "superuser[all] @ git+https://github.com/fitzyracing1/Super.git" # + Cisco AI Defense + Stripe SDKs
From a clone:
Requires Python 3.10+.
pip install -e . # core agent (Duo authz uses requests; no extra dep)
pip install -e '.[security]' # + Cisco AI Defense SDK (cisco-aidefense-sdk)
pip install -e '.[billing]' # + Stripe SDK (usage-based billing)
pip install -e '.[all]' # security + billing
pip install -e '.[dev]' # + pytest / ruff
Configure
Copy .env.example to .env (or use a YAML file — see superuser.example.yaml)
and set values. Key settings:
SUPERUSER_HUMAN_OWNER— the human accountable for the agent's actions.SUPERUSER_APPROVAL_AT— risk threshold for the approval gate (LOW…CRITICAL).AI_DEFENSE_*— Cisco AI Defense credentials/mode (see below).DUO_*— Cisco Duo Agentic Identity authorization (see below).STRIPE_*— Stripe usage-based billing (see below).GITHUB_TOKEN,GITHUB_ALLOWED_REPOS,GITHUB_ALLOW_WRITES— least-privilege GitHub.
For a full console-value → env-var mapping for all three services, see
docs/INTEGRATIONS.md.
Cisco AI Defense
Install the SDK (pip install 'superuser[security]') and provide credentials:
- Explicit inspection of this server's own tool calls/responses:
set
AI_DEFENSE_INSPECTION_API_KEY. - Runtime protection (
agentsec.protect()auto-patches LLM + MCP clients): setAI_DEFENSE_API_MODE_LLM_ENDPOINT+AI_DEFENSE_API_MODE_LLM_API_KEY, or pointAI_DEFENSE_AGENTSEC_CONFIGat anagentsec.yaml(seeagentsec.example.yaml). AI_DEFENSE_MODE:enforce(block),monitor(log only), oroff.
If the SDK is not installed or no credentials are set, the agent still runs but
every result is annotated protected: false / UNPROTECTED — the gap is never
silent. In enforce mode, inspection errors fail closed (the call is
blocked); in monitor mode they fail open (logged, allowed).
Environment variables
| Area | Variables |
|---|---|
| Core | SUPERUSER_CONFIG, SUPERUSER_HUMAN_OWNER, SUPERUSER_APPROVAL_AT, SUPERUSER_COMMAND_TIMEOUT, SUPERUSER_AUDIT_LOG |
| Cisco AI Defense | AI_DEFENSE_ENABLED (default true; set false for local dev), AI_DEFENSE_MODE, AI_DEFENSE_INSPECTION_API_KEY, AI_DEFENSE_API_MODE_LLM_ENDPOINT, AI_DEFENSE_API_MODE_LLM_API_KEY, AI_DEFENSE_AGENTSEC_CONFIG |
| Cisco Duo | DUO_ENABLED, DUO_MODE, DUO_AGENT_ID, DUO_TOKEN_URL, DUO_CLIENT_ID, DUO_CLIENT_SECRET, DUO_AUTHORIZATION_URL, DUO_RESOURCE, DUO_SCOPES |
| Stripe | STRIPE_ENABLED, STRIPE_API_KEY, STRIPE_CUSTOMER_ID, STRIPE_METER_EVENT_NAME, STRIPE_DEFAULT_VALUE |
| GitHub | GITHUB_TOKEN, GITHUB_ALLOWED_REPOS, GITHUB_ALLOW_WRITES, GITHUB_API_URL |
With no keys set the server still runs: Duo and Stripe are off by default, and Cisco AI Defense runs unprotected (clearly flagged) if the SDK/keys are missing.
Run
# Validate configuration and print guardrail/Cisco status, then exit:
superuser --check
# Start the MCP server (stdio transport, for MCP clients like Cursor/Claude):
superuser
# or: python -m superuser
Register with an MCP client
Example client config (stdio):
{
"mcpServers": {
"superuser": {
"command": "superuser",
"env": {
"SUPERUSER_HUMAN_OWNER": "you@example.com",
"AI_DEFENSE_MODE": "enforce",
"AI_DEFENSE_INSPECTION_API_KEY": "..."
}
}
}
}
Test
pytest
Security notes
- The dangerous-command denylist is a backstop, not the primary control. The primary controls are Cisco AI Defense inspection and the approval gate.
- GitHub access fails closed: no token or an empty repo allowlist means no access. Use a fine-grained, least-privilege token.
- Secrets are redacted in the audit log. Keep
.env/*.yamlconfig files out of version control (already in.gitignore).
License
Apache-2.0.
Plans
This project is free, and its license stays as is. Support it through GitHub Sponsors:
- Free: use the code, community support.
- Pro ($49/month): priority issues and support.
- Team ($199/month): priority support for your team plus early access.
superuser MCP questions
How do I add superuser MCP to Claude Code?
Run 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 in your terminal. Add --scope user to make it available in every project.
How do I add superuser MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does superuser MCP provide?
It exposes 8 tools, including system_status, disk_usage, list_processes, run_command, github_get_repo.
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.