Secure Ubuntu MCP Server

A security-focused MCP server for performing safe operations on an Ubuntu system, featuring robust security controls and audit logging.

🔒Security-FirstModel Context Protocol server for safe Ubuntu system operations

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

# 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

# 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

# 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

{ "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.

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

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)

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)

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 )

- 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

- execute_command(command, working_dir=None)- Execute shell commands safely
- get_system_info()- Get OS, memory, and disk information

- search_packages(query)- Search APT repositories
- install_package(package_name)- Check package availability (listing only)

# These are all blocked: ../../../etc/passwd /etc/passwd /tmp/../etc/passwd symlinks_to_sensitive_files

# These are all blocked: echo hello; rm -rf / echo cat /etc/passwd echo $(whoami) ls | rm -rf /

- File size limits prevent memory exhaustion
- Execution timeouts prevent hanging processes
- Output size limits prevent log flooding
- Directory listing limits prevent enumeration attacks

- User attribution
- Timestamp and operation type
- Full path resolution
- Success/failure status
- Security violation details

# Test core functionality python main.py --test

# Run comprehensive security tests python main.py --security-test

# Test MCP protocol directly python test_client.py --simple

"Check my system status and disk space"

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

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

"Look for any error files in my project directory"

- MCP_LOG_LEVEL- Logging level (DEBUG, INFO, WARNING, ERROR)
- MCP_POLICY- Security policy (secure, dev)
- MCP_CONFIG_PATH- Path to custom configuration file

{ "server": { "name": "secure-ubuntu-controller", "version": "1.0.0", "log_level": "INFO" }, "security": { "policy_name": "secure", "allowed_paths": ["~/", "/tmp"], "max_command_timeout": 30, "allow_sudo": false, "audit_actions": true } }

@mcp.tool("your_tool_name") async def your_tool(param: str) -> str: """Tool description for AI assistant""" try: # Use controller methods for safe operations result = controller.safe_operation(param) return json.dumps(result, indent=2) except Exception as e: return json.dumps({"error": str(e)}, indent=2)

def create_custom_policy() -> SecurityPolicy: """Create a custom security policy""" return SecurityPolicy( allowed_paths=["/your/paths"], forbidden_commands=["dangerous", "commands"], # ... other settings )

- 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

- 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

- Verify your user has access to the requested paths
- Check file/directory permissions withls -la

# Enable verbose logging python main.py --log-level DEBUG --policy secure # Check audit logs tail -f /tmp/ubuntu_mcp_audit.log

We welcome contributions! Please see ourContributing Guidelinesfor details.
- Fork the repository
- Create a feature branch:git checkout -b feature/amazing-feature
- Make your changes with tests
- Ensure all tests pass:python main.py --test && python main.py --security-test
- Submit a pull request

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

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.

- Model Context Protocolteam for the excellent protocol
- Security researchers and the infosec community for best practices
- Python security community for ongoing guidance

-

An MCP server for Cisco NSO (Network Services Orchestrator) that exposes NSO data and operations as MCP primitives.