Ubuntu MCP Server

A Model Context Protocol (MCP) server that provides secure, controlled access to Ubuntu system operations. This server allows AI assistants to interact with Ubuntu systems through a well-defined protocol with configurable security policies.

Features

🔒 Security-First Design

Path-based access control: Only allows operations in explicitly permitted directories
Command filtering: Whitelist/blacklist approach for shell commands
Configurable security policies: Safe mode vs development mode
Timeout protection: Prevents runaway processes
No sudo by default: Can be enabled with explicit configuration

🛠 Core Capabilities

File Operations: Read, write, list directories with permission checks
Command Execution: Run shell commands with security controls
Package Management: Search and install packages via apt
System Information: Get OS details, memory, disk usage
Process Management: With appropriate security policies

🏗 Architecture

Modular Design: Clear separation between security, controller, and MCP layers
Production Ready: Includes logging, error handling, and comprehensive testing
Extensible: Easy to add new tools and capabilities

Installation

Clone and setup:

git clone <repository>
cd ubuntu_mcp_server

Create virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

Install dependencies:

pip install -r requirements.txt

Usage

Testing the Controller

Run the built-in tests to verify everything works:

python main.py --test

You should see output like:

=== Testing Ubuntu Controller ===

1. Testing system info...
OS: Ubuntu 24.04.2 LTS
User: your_username
Hostname: your_hostname

2. Testing directory listing...
Found X items in /home/your_username
...

✅ All tests passed!

Running as MCP Server

Start the server with default (safe) security policy:

python main.py

Or with development policy (more permissive):

python main.py --policy dev

Testing with MCP Client

Run the test client to verify MCP protocol functionality:

python test_client.py --simple

Security Policies

Safe Policy (Default)

Allowed paths: ~/, /tmp, /var/tmp, /opt, /usr/local
Forbidden paths: /etc/passwd, /etc/shadow, /root, /boot, /sys, /proc
Allowed commands: Basic commands like ls, cat, echo, apt, git, python3
Forbidden commands: Destructive commands like rm, dd, shutdown, mount
Sudo: Disabled

Development Policy

Allowed paths: Includes /var/log in addition to safe policy paths
Fewer forbidden paths: Only critical system areas protected
More commands allowed: Nearly all commands except destructive ones
Sudo: Enabled (use with caution)

Available MCP Tools

File Operations

list_directory(path) - List directory contents with metadata
read_file(file_path) - Read file contents with size limits
write_file(file_path, content, create_dirs=False) - Write content to file

System Operations

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

Package Management

search_packages(query) - Search for packages using apt
install_package(package_name, use_sudo=False) - Install packages via apt

Configuration

Using config.json

The server can be configured using a config.json file:

{
  "server": {
    "name": "ubuntu-controller",
    "version": "1.0.0",
    "description": "MCP Server for Ubuntu System Control",
    "log_level": "INFO"
  },
  "security": {
    "policy_name": "safe",
    "allowed_paths": ["~/", "/tmp", "/var/tmp"],
    "forbidden_paths": ["/etc/passwd", "/etc/shadow", "/root"],
    "allowed_commands": ["ls", "cat", "echo", "apt", "git"],
    "forbidden_commands": ["rm", "dd", "shutdown", "reboot"],
    "max_command_timeout": 30,
    "allow_sudo": false
  }
}

Environment Variables

MCP_LOG_LEVEL - Set logging level (DEBUG, INFO, WARNING, ERROR)
MCP_POLICY - Set security policy (safe, dev)
MCP_CONFIG_PATH - Path to custom config file

Example Usage with AI Assistants

Claude Desktop Integration

Note: Claude Desktop is not officially available for Linux. However, there are community solutions to run Claude Desktop on Linux by rebuilding the Windows package. Search for "Claude Desktop Linux" tutorials on YouTube or GitHub for installation methods.

Once you have Claude Desktop running on Linux, add to your Claude Desktop configuration file (usually located at ~/.config/claude-desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "ubuntu-controller": {
      "command": "/path/to/ubuntu_mcp_server/.venv/bin/python3",
      "args": ["/path/to/ubuntu_mcp_server/main.py"],
      "env": {
        "MCP_POLICY": "safe"
      }
    }
  }
}

Important:

Replace /path/to/ubuntu_mcp_server/ with the actual absolute path to your project directory
Use the virtual environment Python interpreter (.venv/bin/python3) to ensure all dependencies are available
Both the command and args paths must be absolute paths

For example, if you cloned the project to /home/username/ubuntu_mcp_server/, the configuration would be:

{
  "mcpServers": {
    "ubuntu-controller": {
      "command": "/home/username/ubuntu_mcp_server/.venv/bin/python3",
      "args": ["/home/username/ubuntu_mcp_server/main.py"],
      "env": {
        "MCP_POLICY": "safe"
      }
    }
  }
}

Why use the virtual environment Python? The Ubuntu MCP Server requires the mcp package and other dependencies that are installed in the virtual environment. Using the system Python (python3) will result in import errors because it doesn't have access to these packages.

After adding this configuration:

Restart Claude Desktop
The Ubuntu Controller tools will be available in your conversations
You can ask Claude to perform system operations like "Check my disk space" or "List files in my home directory"

Verification: If the integration is successful, you should see "ubuntu-controller" listed as a connected server in Claude Desktop's status, and Claude will have access to system control tools.

Alternative MCP Clients

If you prefer not to use Claude Desktop on Linux, you can use other MCP-compatible clients:

1. Direct MCP Protocol Testing:

# Test with the built-in client
python test_client.py

2. Custom MCP Client: You can build your own MCP client using the mcp Python package to interact with the server programmatically.

3. Web-based Solutions: Some community projects provide web interfaces for MCP servers - check GitHub for "MCP web client" projects.

Example Interactions

Once connected to an AI assistant, you can request operations like:

System Information:

"What's the current system status and available disk space?"

File Management:

"List the contents of my home directory and show me the largest files"

Development Tasks:

"Check if Node.js is installed, and if not, install it"

Log Analysis:

"Look for any recent errors in the system logs" (requires dev policy)

Security Considerations

Production Deployment

For production use:

Review security policies carefully for your environment
Use minimal permissions - start with safe policy and expand as needed
Monitor logs for any suspicious activity
Regular updates of the server and dependencies
Network isolation if running remotely

Security Features

Path traversal protection: Prevents access outside allowed directories
Command injection prevention: Validates and sanitizes all commands
Resource limits: Timeouts and file size limits prevent resource exhaustion
Audit logging: All operations are logged for security monitoring

Development

Adding New Tools

To add a new MCP tool, edit the create_ubuntu_mcp_server function:

@mcp.tool("your_new_tool")
async def your_new_tool(param1: str, param2: int = 10) -> str:
    """Description of your tool
    
    Args:
        param1: Description of parameter
        param2: Optional parameter with default
        
    Returns:
        Description of return value
    """
    try:
        # Your implementation here
        result = controller.your_method(param1, param2)
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)}, indent=2)

Extending Security Policies

Create custom security policies by extending the SecurityPolicy class:

def create_custom_policy() -> SecurityPolicy:
    return SecurityPolicy(
        allowed_paths=["/your/custom/paths"],
        forbidden_paths=["/sensitive/areas"],
        allowed_commands=["your", "allowed", "commands"],
        forbidden_commands=["dangerous", "commands"],
        max_command_timeout=60,
        allow_sudo=True  # Use with extreme caution
    )

Testing

Run the comprehensive test suite:

# Test core functionality
python main.py --test

# Test MCP client integration
python test_client.py --simple

# Test with actual MCP protocol
python test_client.py

Troubleshooting

Common Issues

Server starts then appears to hang: This is normal behavior! MCP servers are designed to run indefinitely and communicate via stdin/stdout. The server is waiting for MCP protocol messages from Claude Desktop or another MCP client.

Import errors for MCP (ModuleNotFoundError: No module named 'mcp'): This usually means Claude Desktop is trying to use the system Python instead of the virtual environment Python. Make sure your Claude Desktop configuration uses the full path to the virtual environment Python interpreter:

"command": "/path/to/ubuntu_mcp_server/.venv/bin/python3"

NOT just "command": "python3"

If you still have issues:

# Activate virtual environment and reinstall
source .venv/bin/activate
pip install --upgrade mcp

Permission denied errors:

Check that your user has access to the requested paths
Verify security policy allows the operation
For sudo operations, ensure allow_sudo: true in config

Command timeout errors:

Increase max_command_timeout in security policy
Check if command is hanging or requires interaction

File not found errors:

Verify path is within allowed directories
Check file permissions and existence

Testing the Server

To verify the server works correctly:

# Test core functionality
python main.py --test

# Test server startup (should stay running)
python main.py --policy safe
# Press Ctrl+C to stop

# Test with development policy
python main.py --policy dev

Debug Mode

Enable debug logging:

python main.py --log-level DEBUG

Or set environment variable:

export MCP_LOG_LEVEL=DEBUG
python main.py

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Code Style

Follow PEP 8 style guidelines
Add type hints for all functions
Include comprehensive docstrings
Write tests for new features

License

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

Security Disclosure

If you discover a security vulnerability, please send an email to [security@yourproject.com] instead of creating a public issue.

Changelog

v1.0.0

Initial release
Core file and command operations
Security policy system
MCP protocol integration
Package management tools
Comprehensive testing suite

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A secure protocol server that allows AI assistants to safely interact with Ubuntu systems through controlled file operations, command execution, package management, and system information retrieval.

Related MCP Servers

Shell MCP Server
blazickjp
-
security
A
license
-
quality
A secure server that enables AI applications to execute shell commands in specified directories, supporting multiple shell types (bash, sh, cmd, powershell) with built-in security features like directory isolation and timeout control.
Last updated -
9
Python
Apache 2.0
Scrapybara MCP
Scrapybara
A
security
A
license
A
quality
A Model Context Protocol server that enables AI clients to interact with virtual Ubuntu desktops, allowing them to browse the web, run code, and control instances through mouse/keyboard actions and bash commands.
Last updated -
5
9
JavaScript
MIT License
Unity MCP Integration
quazaai
-
security
A
license
-
quality
A server that enables AI assistants to understand and interact with Unity projects in real-time, providing access to scene hierarchy, project settings, and the ability to execute code directly in the Unity Editor.
Last updated -
40
MIT License
MCP Server
tcpipuk
-
security
A
license
-
quality
A server that enables AI assistants like Claude to safely run Python code and access websites, processing data for better AI understanding while providing helpful error messages.
Last updated -
2
Python
GPL 3.0

View all related MCP servers