Secure Ubuntu MCP Server

Security-First Model Context Protocol server for safe Ubuntu system operations

A hardened, production-ready Model Context Protocol (MCP) server that provides AI assistants with secure, controlled access to Ubuntu system operations. Built with comprehensive security controls, audit logging, and defense-in-depth principles.

Key Features

Security-First Architecture

• Path traversal protection - Symlink resolution with allowlist/denylist controls
• Command sanitization - Shell injection prevention with safe argument parsing
• Resource limits - File size, execution timeouts, and output size controls
• Comprehensive audit logging - All operations logged with user attribution
• Defense in depth - Multiple security layers with fail-safe defaults

Core Capabilities

• File Operations - Read, write, and list directories with permission validation
• Command Execution - Safe shell command execution with whitelist/blacklist filtering
• System Information - OS details, memory, and disk usage monitoring
• Package Management - APT package search and listing (installation requires explicit config)

Production Ready

• Modular design with clear separation of concerns
• Comprehensive error handling with meaningful error messages
• Extensive test suite including security validation tests
• Configurable policies for different use cases and environments
• Zero-dependency security - Core security doesn't rely on external packages

Quick Start

Prerequisites

• Ubuntu 18.04+ (tested on 20.04, 22.04, 24.04)
• Python 3.9 or higher
• Standard Unix utilities (ls, cat, echo, etc.)

Installation

# Clone the repository
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify installation with built-in tests
python main.py --test

Basic Usage

# Start with secure policy (recommended)
python main.py --policy secure

# Start with development policy (more permissive)
python main.py --policy dev

# Test security measures
python main.py --security-test

Integration

Claude Desktop

Getting Claude Desktop on Linux

Official Support: Claude Desktop doesn't officially support Linux, but the community has created solutions!

Recommended Method: Use the community Debian package by @aaddrick:

# Download and install Claude Desktop for Linux
wget https://github.com/aaddrick/claude-desktop-debian/releases/latest/download/claude-desktop_latest_amd64.deb
sudo dpkg -i claude-desktop_latest_amd64.deb
sudo apt-get install -f  # Fix any dependency issues

For other methods and troubleshooting, see: https://github.com/aaddrick/claude-desktop-debian

Configuration

Once Claude Desktop is installed, add to your configuration (~/.config/claude-desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "secure-ubuntu": {
      "command": "/path/to/secure-ubuntu-mcp/.venv/bin/python3",
      "args": ["/path/to/secure-ubuntu-mcp/main.py", "--policy", "secure"],
      "env": {
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Important: Use absolute paths and the virtual environment Python interpreter

Verification: After restarting Claude Desktop, you should see "secure-ubuntu" listed as a connected server, and Claude will have access to system control tools.

Other MCP Clients

The server implements the standard MCP protocol and works with any MCP-compatible client:

# Example with mcp Python client
import asyncio
from mcp.client import ClientSession

async def example():
    # Connect to the server
    # Implementation depends on your MCP client
    pass

Security Policies

Secure Policy (Default)

Recommended for production and untrusted environments:

• Allowed Paths: ~/, /tmp, /var/tmp
• Forbidden Paths: /etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
• Command Whitelist: ls, cat, echo, pwd, whoami, date, find, grep, apt (search only)
• Resource Limits: 1MB files, 15s timeouts, 256KB output
• Sudo: Disabled
• Shell Execution: Disabled (uses safe direct execution)

Development Policy

More permissive for development environments:

• Additional Allowed Paths: /opt, /usr/local
• Fewer Restrictions: Access to more system areas
• Larger Limits: 10MB files, 60s timeouts, 1MB output
• More Commands: Most development tools allowed
• Sudo: Still disabled by default (can be enabled)

Custom Policies

Create your own security policy:

from main import SecurityPolicy

custom_policy = SecurityPolicy(
    allowed_paths=["/your/custom/paths"],
    forbidden_paths=["/sensitive/areas"],
    allowed_commands=["safe", "commands"],
    forbidden_commands=["dangerous", "commands"],
    max_command_timeout=30,
    allow_sudo=False,  # Use with extreme caution
    audit_actions=True
)

Available Tools

File Operations

• list_directory(path) - List directory contents with metadata
• read_file(file_path) - Read file contents with size validation
• write_file(file_path, content, create_dirs=False) - Write with atomic operations

System Operations

• execute_command(command, working_dir=None) - Execute shell commands safely
• get_system_info() - Get OS, m…