Sudo MCP Server

A Model Context Protocol (MCP) server that enables Claude Code to execute sudo commands securely while keeping your sudo password hidden from the LLM. This ensures that sensitive credentials never appear in conversation logs or context.

Features

• 🔒 Secure sudo password handling - password never exposed to the LLM
• ⚡ Execute sudo commands directly from Claude Code
• 📜 Run multi-line bash scripts with sudo privileges
• 📦 Install packages with apt-get (Debian/Ubuntu)
• 🔧 Manage systemd services (start, stop, restart, etc.)
• ✅ Check sudo availability and credential cache status

Installation

Install via your AI coding assistant CLI:

Claude Code

claude mcp add --scope user sudo-mcp npx @davidfei/sudo-mcp

You'll be prompted to enter your sudo password during setup.

Alternatively, you can provide the password directly:

claude mcp add --scope user sudo-mcp --env SUDO_PASSWORD=your-password -- npx @davidfei/sudo-mcp

Codex

Note: This MCP server requires Codex version 0.40.0 (not the latest version).

codex mcp add sudo-mcp --env SUDO_PASSWORD=your-password -- npx @davidfei/sudo-mcp

Gemini

gemini mcp add sudo-mcp npx @davidfei/sudo-mcp -t stdio -s user -e SUDO_PASSWORD=your-password

Available Tools

Once installed, Claude Code will have access to these sudo tools:

1. sudo_exec

Execute a single command with sudo privileges.

Parameters:

• command (required): The command to execute (without 'sudo' prefix)

Examples:

• "Use sudo to update package lists" → executes sudo apt-get update
• "Create a directory at /opt/myapp with sudo" → executes sudo mkdir /opt/myapp
• "Check the nginx configuration with sudo" → executes sudo nginx -t

2. sudo_exec_script

Execute a multi-line bash script with sudo privileges.

Parameters:

• script (required): The bash script content to execute

Examples:

• "Run this deployment script with sudo: [multi-line script]"
• "Execute this system maintenance script with elevated privileges"

3. check_sudo

Check if sudo is available and if credentials are currently cached.

Example: "Check if sudo is available on this system"

4. sudo_apt_install

Install packages using apt-get (Debian/Ubuntu systems).

Parameters:

• packages (required): Space-separated list of package names

Examples:

• "Install nginx using sudo"
• "Install python3-pip and git with sudo"

5. sudo_systemctl

Control systemd services with sudo.

Parameters:

• action (required): One of: start, stop, restart, reload, enable, disable, status
• service (required): Name of the systemd service

Examples:

• "Restart nginx service with sudo"
• "Enable docker service to start on boot"
• "Check the status of postgresql service"

Common Use Cases

System Administration

You: "Update the package list and install htop"
Claude: [Uses sudo_exec to run apt-get update, then sudo_apt_install for htop]

You: "Restart the nginx service"
Claude: [Uses sudo_systemctl with action=restart, service=nginx]

File Management

You: "Create a directory /opt/myapp and set ownership to www-data"
Claude: [Uses sudo_exec_script to run multiple commands]

Service Management

You: "Check if docker is running, and start it if it's not"
Claude: [Uses sudo_systemctl to check status, then conditionally starts]

Security

This tool executes commands with elevated privileges. Key security features:

• 🔒 Password Protection: Your sudo password is never exposed to the LLM or logged
• 🛡️ Secure Transport: Password passed via stdin, not command arguments
• ⏱️ Timeout Protection: Commands have built-in timeouts to prevent hanging
• 🔍 Audit Trail: All sudo operations are logged by the system

For detailed security information, best practices, and troubleshooting, see DEVELOPMENT.md.

Important: Always review what commands Claude suggests before allowing execution.

Troubleshooting

Quick Fixes

Authentication Issues: Verify your SUDO_PASSWORD is correct and your user has sudo privileges.

Command Timeouts: Single commands timeout after 30 seconds, scripts after 60 seconds, apt operations after 5 minutes.

"sudo: a terminal is required to read the password": Ensure SUDO_PASSWORD environment variable is set correctly.

For detailed troubleshooting, development setup, and advanced configuration, see DEVELOPMENT.md.

Limitations

• Linux/macOS only: This tool is designed for Unix-like systems with sudo
• Command parsing: Complex commands with pipes may need to be wrapped in a script
• Interactive commands: Commands requiring user interaction are not supported
• Timeout constraints: Long-running operations may timeout

Development & Contributing

For local development setup, testing, and contribution guidelines, see DEVELOPMENT.md.

For technical details about the MCP implementation, see CLAUDE.md.

License

MIT

Support

Report issues at: GitLab Issues

Disclaimer

This tool executes commands with elevated privileges. Always review what commands Claude suggests before allowing them to execute. The authors are not responsible for any system damage caused by misuse of this tool.