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

Basic Usage

🔧 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:

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):

⚠️ 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:

🛡️ 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:

🔍 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, memory, and disk information

Package Management

• search_packages(query) - Search APT repositories

• install_package(package_name) - Check package availability (listing only)

🔒 Security Features

Protection Against Common Attacks

Path Traversal Prevention:

Command Injection Prevention:

Resource Exhaustion Protection:

• File size limits prevent memory exhaustion

• Execution timeouts prevent hanging processes

• Output size limits prevent log flooding

• Directory listing limits prevent enumeration attacks

Audit Trail

All operations are logged with:

• User attribution

• Timestamp and operation type

• Full path resolution

• Success/failure status

• Security violation details

🧪 Testing

Functionality Tests

Security Validation

Manual Testing

📊 Example Usage

Once integrated with an AI assistant:

System Monitoring:

"Check my system status and disk space"

File Management:

"List the files in my home directory and show me the largest ones"

Development Tasks:

"Check if Python is installed and show me the version"

Log Analysis:

"Look for any error files in my project directory"

⚙️ Configuration

Environment Variables

• MCP_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)

• MCP_POLICY - Security policy (secure, dev)

• MCP_CONFIG_PATH - Path to custom configuration file

Configuration File

Create config.json for custom settings:

🛠️ Development

Adding New Tools

Extending Security

🔧 Troubleshooting

Common Issues

"Server appears to hang"

• This is normal! MCP servers run continuously and communicate via stdio

• The server is waiting for MCP protocol messages

"ModuleNotFoundError: No module named 'mcp'"

• Ensure you're using the virtual environment Python interpreter

• Check your Claude Desktop config uses the full path to .venv/bin/python3

"SecurityViolation" errors

• Check if the path/command is allowed by your security policy

• Review audit logs at /tmp/ubuntu_mcp_audit.log

• Consider using development policy for testing

"Permission denied" errors

• Verify your user has access to the requested paths

• Check file/directory permissions with ls -la

Debug Mode

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes with tests

4. Ensure all tests pass: python main.py --test && python main.py --security-test

5. Submit a pull request

Code Standards

• Follow PEP 8 style guidelines

• Add type hints for all public functions

• Include comprehensive docstrings

• Write tests for new functionality

• Maintain security-first principles

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔐 Security Disclosure

If you discover a security vulnerability, please email [radjackbartok@proton.me] instead of creating a public issue. We take security seriously and will respond promptly.

🙏 Acknowledgments

• Model Context Protocol team for the excellent protocol

• Security researchers and the infosec community for best practices

• Python security community for ongoing guidance

📈 Roadmap

• Enhanced Logging - Structured JSON logging with more context

• Container Support - Docker integration and container-aware policies

• Network Tools - Safe networking utilities (ping, traceroute, etc.)

• Process Management - Safe process monitoring and control

• Configuration UI - Web interface for policy management

• Integration Tests - Comprehensive end-to-end testing

• Performance Optimization - Caching and performance improvements

• Multi-User Support - Role-based access controls

Made for the security-conscious AI community

💡 Pro Tip: Start with the secure policy and gradually increase permissions as needed. It's easier to add permissions than to recover from a security incident!