# Sudo Mcp

> MCP server for executing privileged commands via polkit (Linux) and sudo (macOS)

- **Type:** MCP server
- **Install:** `agentstack add mcp-hughesjs-sudo-mcp`
- **Verified:** Pending review
- **Seller:** [hughesjs](https://agentstack.voostack.com/s/hughesjs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hughesjs](https://github.com/hughesjs)
- **Source:** https://github.com/hughesjs/sudo-mcp

## Install

```sh
agentstack add mcp-hughesjs-sudo-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/hughesjs/sudo-mcp/releases/latest), extract, run `.\install.ps1` as Administrator, then:
```powershell
claude mcp add sudo-mcp "$env:ProgramFiles\sudo-mcp\sudo-mcp.exe"
```

**macOS:** Download from [releases](https://github.com/hughesjs/sudo-mcp/releases/latest), extract, run `./install.sh`, then:
```bash
claude mcp add sudo-mcp /usr/local/bin/sudo-mcp           # Configure Claude Code
```

**Arch Linux:**
```bash
yay -S sudo-mcp                            # Install from AUR
claude mcp add sudo-mcp /usr/bin/sudo-mcp  # Configure Claude Code
```

**Fedora/RHEL/CentOS:**
```bash
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](https://github.com/hughesjs/sudo-mcp/releases/latest), 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](https://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](https://github.com/hughesjs/sudo-mcp/releases/latest) to download the latest version for your architecture.

**Step 2**: Extract and install:

**x86_64 (Intel/AMD)**:
```bash
# 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)**:
```bash
# 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](https://github.com/hughesjs/sudo-mcp/releases/latest) to download `sudo-mcp-win-x64-vVERSION.zip`.

**Step 2**: Extract and install (as Administrator):
```powershell
Expand-Archive sudo-mcp-win-x64-vVERSION.zip -DestinationPath .
cd sudo-mcp-win-x64-vVERSION
.\install.ps1
```

### Arch Linux (AUR)

**From AUR** (Recommended):
```bash
yay -S sudo-mcp
```

**Manual PKGBUILD**:

If you prefer to build manually, visit the [Releases Page](https://github.com/hughesjs/sudo-mcp/releases/latest), download the PKGBUILD, and run:
```bash
makepkg -si
```

### Fedora/RHEL/CentOS (COPR)

**From COPR** (Recommended):
```bash
# 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](https://github.com/hughesjs/sudo-mcp/releases/latest), download the `sudo-mcp.spec` file, and use `rpmbuild` or `mock`.

### From Source (Development)

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

```bash
# 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

```bash
sudo-mcp --help
```

### Uninstall

```bash
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):**
```bash
sudo-mcp
```

**Custom blocklist:**
```bash
sudo-mcp --blocklist-file /path/to/custom-blocklist.json
```

**No blocklist (MAXIMUM DANGER):**
```bash
sudo-mcp --no-blocklist
```

**Custom timeout and audit log:**
```bash
sudo-mcp --timeout 60 --audit-log /home/user/.sudo-mcp/audit.log
```

**Display help:**
```bash
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:**
```json
{
  "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:**
```bash
sudo-mcp --blocklist-file examples/blocklist-permissive.json
```

**Customising the blocklist:**

Create your own JSON file and pass it via `--blocklist-file`:
```bash
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.

```bash
sudo-mcp --no-blocklist
```

### Audit Logging

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

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

**Custom log location:**
```bash
sudo-mcp --audit-log /home/user/.sudo-mcp/audit.log
```

**Ensure the log directory exists and is writable:**
```bash
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:**
```json
{
  "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:**
```json
{
  "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:
```bash
# 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`:
```powershell
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:**
```bash
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`

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

### Cursor

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

```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
5. **User approves or denies** the privilege escalation
6. **Command executes** (if approved) and output is captured
7. **AuditLogger records** the execution attempt with full details
8. **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:
```bash
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](https://github.com/hughesjs)
- **Source:** [hughesjs/sudo-mcp](https://github.com/hughesjs/sudo-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hughesjs-sudo-mcp
- Seller: https://agentstack.voostack.com/s/hughesjs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.