Sudo Mcp

sudo-mcp

[](https://github.com/hughesjs/sudo-mcp/actions/workflows/ci-pipeline.yml) [](https://github.com/hughesjs/sudo-mcp/actions/workflows/cd-pipeline.yml) [](https://aur.archlinux.org/packages/sudo-mcp) [](https://aur.archlinux.org/packages/sudo-mcp) [](https://aur.archlinux.org/packages/sudo-mcp) [](https://copr.fedoraproject.org/coprs/hughesjs/sudo-mcp/) [](https://github.com/hughesjs/sudo-mcp/blob/master/LICENSE) [](https://github.com/hughesjs/custom-badges)

MCP (Model Context Protocol) server that allows AI models to execute commands with elevated privileges via sudo. On Linux, privilege escalation uses polkit/pkexec with your desktop authentication agent. On macOS, it uses sudo -A with a native password dialogue via osascript. On Windows 11 24H2+, it uses the built-in sudo command with UAC elevation.

> [!CAUTION] > ## SECURITY WARNING > > As G.K. Chesterton said: "Don't ever take a fence down until you know the reason it was put up". > > This is an inherently dangerous tool. By design, it allows an AI model to execute commands with root privileges on your system. While basic safeguards can be configured (command blocklist, audit logging), NO SECURITY MEASURE IS PERFECT. > > USE AT YOUR OWN RISK. This tool could potentially: > - Destroy data through file system operations > - Compromise system security by modifying critical configurations > - Modify or delete critical system files including kernel and boot files > - Execute malicious commands if the blocklist is bypassed or disabled > - Escalate privileges beyond what you intended > - Expose sensitive information through command output > > The --no-blocklist flag removes ALL command validation. Using this option gives the AI unrestricted root access to your system. > > You have been warned. > > Despite this, this tool is still safer than OpenClaw, at least you're asked for your password to do dumb stuff.

Overview

sudo-mcp is a C# MCP server that integrates with Claude Desktop (or any MCP client) to enable execution of privileged commands. On Linux it uses polkit/pkexec for authentication; on macOS it uses sudo -A with a native osascript password dialogue; on Windows 11 it uses the built-in sudo command with UAC elevation. All platforms support configurable command validation.

Key Features:

• 🔐 Platform-Native Privilege Escalation - polkit/pkexec on Linux, sudo with native macOS password dialogue, Windows sudo with UAC
• ✅ Configurable Command Validation - Optional blocklist to prevent dangerous operations (Linux, macOS, and Windows patterns)
• 📝 Comprehensive Audit Logging - Every command attempt logged with full details
• ⚙️ Runtime Configuration - Command-line arguments for blocklist, timeouts, and logging
• 🚀 .NET 10 - Built on the latest .NET platform with C# 12
• 🍎 Cross-Platform - Supports Linux (x64/ARM64), macOS (Intel/Apple Silicon), and Windows 11 (x64)

Quick Start (Claude Code)

Windows 11 (24H2+): Download the .zip from releases, extract, run .\install.ps1 as Administrator, then:

claude mcp add sudo-mcp "$env:ProgramFiles\sudo-mcp\sudo-mcp.exe"

macOS: Download from releases, extract, run ./install.sh, then:

claude mcp add sudo-mcp /usr/local/bin/sudo-mcp           # Configure Claude Code

Arch Linux:

yay -S sudo-mcp                            # Install from AUR
claude mcp add sudo-mcp /usr/bin/sudo-mcp  # Configure Claude Code

Fedora/RHEL/CentOS:

sudo dnf copr enable hughesjs/sudo-mcp     # Enable COPR repository
sudo dnf install sudo-mcp                  # Install from COPR
claude mcp add sudo-mcp /usr/bin/sudo-mcp  # Configure Claude Code

Other distributions: Download from releases, extract, run ./install.sh, then use claude mcp add.

Restart Claude Code and approve authentication prompts when commands execute. Read the [security warning](#%EF%B8%8F-security-warning) above before use.

Prerequisites

• (If Building) .NET 10 SDK - Install from dotnet.microsoft.com
• Linux, macOS, or Windows 11 - Supported platforms
• Linux: Polkit authentication agent - Required for graphical authentication (typically included in desktop environments)
• macOS: sudo (included by default) - Uses native osascript password dialogue for authentication
• Windows 11 24H2+: Built-in sudo command - enable in Settings > System > For Developers
• Claude Desktop - Or any MCP-compatible client

Installation

Binary Release (Linux and macOS)

Step 1: Visit the Releases Page to download the latest version for your architecture.

Step 2: Extract and install:

x86_64 (Intel/AMD):

# Replace VERSION with the version you downloaded (e.g., 0.1.0)
tar -xzf sudo-mcp-x64-vVERSION.tar.gz
cd sudo-mcp-x64-vVERSION
chmod +x install.sh
./install.sh

ARM64 (aarch64):

# Replace VERSION with the version you downloaded (e.g., 0.1.0)
tar -xzf sudo-mcp-arm64-vVERSION.tar.gz
cd sudo-mcp-arm64-vVERSION
chmod +x install.sh
./install.sh

Windows (Binary Release)

Step 1: Visit the Releases Page to download sudo-mcp-win-x64-vVERSION.zip.

Step 2: Extract and install (as Administrator):

Expand-Archive sudo-mcp-win-x64-vVERSION.zip -DestinationPath .
cd sudo-mcp-win-x64-vVERSION
.\install.ps1

Arch Linux (AUR)

From AUR (Recommended):

yay -S sudo-mcp

Manual PKGBUILD:

If you prefer to build manually, visit the Releases Page, download the PKGBUILD, and run:

makepkg -si

Fedora/RHEL/CentOS (COPR)

From COPR (Recommended):

# Enable the COPR repository
sudo dnf copr enable hughesjs/sudo-mcp

# Install sudo-mcp
sudo dnf install sudo-mcp

Supported distributions:

• Fedora 40, 41, 42, Rawhide (x86_64, aarch64)
• EPEL 9 (x86_64, aarch64)

Manual specfile:

If you prefer to build manually, visit the Releases Page, download the sudo-mcp.spec file, and use rpmbuild or mock.

From Source (Development)

git clone https://github.com/hughesjs/sudo-mcp.git
cd sudo-mcp
chmod +x scripts/install.sh
./scripts/install.sh

This builds from source and installs to /usr/bin/sudo-mcp with default configuration.

Manual Build and Installation

# Clone and build
git clone https://github.com/hughesjs/sudo-mcp.git
cd sudo-mcp

# Build self-contained binary
dotnet publish src/SudoMcp/SudoMcp.csproj \
    -c Release \
    -r linux-x64 \
    --self-contained \
    -o ./publish \
    /p:PublishSingleFile=true

# Install system-wide
sudo cp publish/SudoMcp /usr/bin/sudo-mcp
sudo chmod +x /usr/bin/sudo-mcp

# Set up log directory
sudo mkdir -p /var/log/sudo-mcp
sudo chown $USER:$USER /var/log/sudo-mcp

Verify Installation

sudo-mcp --help

Uninstall

chmod +x scripts/uninstall.sh
./scripts/uninstall.sh

Command-Line Options

sudo-mcp supports the following command-line arguments for runtime configuration:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --blocklist-file | -b | Path to custom blocklist JSON file | Embedded default | | --no-blocklist | - | DANGEROUS: Disable all command validation | false | | --audit-log | -a | Path to audit log file | Linux: /var/log/sudo-mcp/audit.log, macOS: ~/Library/Logs/sudo-mcp/audit.log, Windows: %LOCALAPPDATA%\sudo-mcp\audit.log | | --timeout | -t | Command execution timeout in seconds | 15 |

Examples

Default configuration (with blocklist):

sudo-mcp

Custom blocklist:

sudo-mcp --blocklist-file /path/to/custom-blocklist.json

No blocklist (MAXIMUM DANGER):

sudo-mcp --no-blocklist

Custom timeout and audit log:

sudo-mcp --timeout 60 --audit-log /home/user/.sudo-mcp/audit.log

Display help:

sudo-mcp --help

Configuration

Blocklist Configuration

sudo-mcp includes an embedded default blocklist that prevents execution of dangerous commands using three strategies:

1. Exact Matches - Specific dangerous commands (e.g., rm -rf /)
2. Regex Patterns - Pattern-based blocking for classes of operations
3. Blocked Binaries - Specific executables regardless of arguments

Example blocklist:

{
  "BlockedCommands": {
    "ExactMatches": [
      "rm -rf /",
      "mkfs",
      "dd"
    ],
    "RegexPatterns": [
      "^rm\\s+(-rf?|--recursive)\\s+/\\s*$",
      "^dd\\s+if=.+\\s+of=/dev/(sd[a-z]|nvme[0-9]n[0-9]).*$",
      "^mkfs\\..*"
    ],
    "BlockedBinaries": [
      "mkfs.ext4",
      "shred",
      "cryptsetup"
    ]
  }
}

Example blocklist files are provided in the examples/ directory:

• blocklist-default.json - Exact copy of embedded default (reference implementation)
• blocklist-permissive.json - Relaxed rules for development environments
• blocklist-strict.json - Enhanced security for production-adjacent environments
• blocklist-minimal.json - Bare minimum for testing in disposable VMs

See [examples/blocklist-README.md](examples/blocklist-README.md) for detailed documentation.

Using an example blocklist:

sudo-mcp --blocklist-file examples/blocklist-permissive.json

Customising the blocklist:

Create your own JSON file and pass it via --blocklist-file:

sudo-mcp --blocklist-file /etc/sudo-mcp/my-blocklist.json

Disabling the blocklist:

⚠️ WARNING: Only use --no-blocklist in isolated/test environments where you fully accept the risk.

sudo-mcp --no-blocklist

Audit Logging

All command execution attempts (both allowed and denied) are logged in JSON format:

{
  "Timestamp": "2026-01-11T18:45:00Z",
  "EventType": "CommandExecuted",
  "Command": "systemctl restart nginx",
  "User": "james",
  "ExitCode": 0,
  "Success": true
}

Custom log location:

sudo-mcp --audit-log /home/user/.sudo-mcp/audit.log

Ensure the log directory exists and is writable:

sudo mkdir -p /var/log/sudo-mcp
sudo chown $USER:$USER /var/log/sudo-mcp

MCP Client Integration

After installation, configure your MCP client to use sudo-mcp.

Claude Desktop

Configuration file location:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Basic configuration:

{
  "mcpServers": {
    "sudo-mcp": {
      "command": "/usr/bin/sudo-mcp"
    }
  }
}

On macOS, use /usr/local/bin/sudo-mcp (or the Homebrew prefix path) instead of /usr/bin/sudo-mcp.

Custom configuration:

{
  "mcpServers": {
    "sudo-mcp": {
      "command": "/usr/bin/sudo-mcp",
      "args": [
        "--blocklist-file",
        "/home/YOUR_USERNAME/.config/sudo-mcp/blocklist.json",
        "--timeout",
        "30"
      ]
    }
  }
}

Claude Code

Using the CLI (Recommended):

After installing the binary, simply run:

# Linux
claude mcp add sudo-mcp /usr/bin/sudo-mcp

# macOS
claude mcp add sudo-mcp /usr/local/bin/sudo-mcp

On Windows, use %ProgramFiles%\sudo-mcp\sudo-mcp.exe:

claude mcp add sudo-mcp "$env:ProgramFiles\sudo-mcp\sudo-mcp.exe"

This automatically configures sudo-mcp in your Claude Code settings.

With custom arguments:

claude mcp add sudo-mcp /usr/bin/sudo-mcp -- --timeout 30 --blocklist-file /path/to/custom-blocklist.json

Manual configuration:

Alternatively, you can manually edit the configuration file:

• Linux: ~/.config/claude/config.json
• macOS: ~/Library/Application Support/Claude/config.json

{
  "mcpServers": {
    "sudo-mcp": {
      "command": "/usr/bin/sudo-mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings or project-specific .cursor/mcp.json:

{
  "mcpServers": {
    "sudo-mcp": {
      "command": "/usr/bin/sudo-mcp"
    }
  }
}

See [examples/](examples/) directory for more configuration examples.

Usage Examples

Once configured with Claude Desktop, you can ask Claude to execute commands:

Safe command:

User: "Check if nginx is running"
Claude: [Uses sudo-mcp to execute: systemctl status nginx]

Command requiring authentication:

User: "Restart the nginx service"
Claude: [Uses sudo-mcp to execute: systemctl restart nginx]
[Polkit authentication dialog appears]
[User approves the action]

Blocked command (with blocklist enabled):

User: "Format /dev/sda"
Claude: [sudo-mcp blocks the command]
"This command is blocked for safety: matches dangerous pattern"

How It Works

1. Claude requests command execution via MCP protocol over stdio
2. sudo-mcp receives the request and validates the command
3. CommandValidator checks the command against the blocklist (if enabled)
4. If allowed, the platform executor runs the command with elevated privileges:

• Linux: pkexec sudo - polkit authentication dialogue appears
• macOS: sudo -A - native macOS password dialogue appears via osascript
• Windows: sudo cmd /c - UAC elevation prompt appears

1. User approves or denies the privilege escalation
2. Command executes (if approved) and output is captured
3. AuditLogger records the execution attempt with full details
4. Results returned to Claude with stdout/stderr/exit code

Architecture

Claude Desktop (MCP Client)
    ↓ JSON-RPC over stdio
MCP Server (stdio transport)
    ↓
SudoExecutionTool
    ↓
CommandValidator → [validate against blocklist]
    ↓
IPrivilegedExecutor
    ├─ PkexecExecutor (Linux)    → [spawn pkexec → sudo process]
    ├─ SudoExecutor (macOS)      → [spawn sudo -A with osascript askpass]
    └─ WindowsSudoExecutor (Win) → [spawn sudo cmd /c]
    ↓
AuditLogger → [log to audit file]

Security Considerations

See [SECURITY.md](SECURITY.md) for comprehensive security documentation.

Key Limitations

• Blocklist bypass: Regex patterns can potentially be circumvented
• LLM context: The AI may not fully understand command implications
• No rollback: Executed commands cannot be undone
• Log tampering: Audit logs can be deleted with sudo access
• Linux GUI required: pkexec requires a polkit authentication agent (graphical session)
• macOS credential caching: sudo caches credentials for a timeout period, meaning subsequent commands may not prompt
• Windows sudo requirement: Requires Windows 11 24H2+ with sudo enabled in Developer Settings
• Windows credential caching: UAC may remember elevation for a session

Recommended Practices

• Run in isolated environment: Use a dedicated VM or container
• Review audit logs regularly: Check /var/log/sudo-mcp/audit.log
• Start with blocklist: Only use --no-blocklist when absolutely necessary
• Test in safe environment: Verify behaviour before production use
• Monitor system changes: Use file integrity monitoring (e.g., AIDE, Tripwire)

Troubleshooting

pkexec authentication fails

Problem: Authorization failed (exit code 127)

Solution: Ensure your user is in the appropriate group (e.g., sudo, wheel) and polkit policies allow the action:

groups $USER
pkexec whoami  # Test pkexec authentication

Authentication dialog doesn't appear

Problem: No polkit dialog shown

Solution: Ensure a polki

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hughesjs
• Source: hughesjs/sudo-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.