# ubuntu_mcp_server
## 基本信息
- Slug: `pazuzu1w-ubuntu_mcp_server`
- Source: modelscope
- Publisher: @pazuzu1w/ubuntu_mcp_server
- Categories: shell-access / file-systems / command-line
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@pazuzu1w/ubuntu_mcp_server
## 简介
暂无描述。
## 安装提示

```bash
# 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
```

## MCP Server 详情

# Secure Ubuntu MCP Server

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

A hardened, production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Security Focused](https://img.shields.io/badge/security-focused-green.svg)](#security-features)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io/)

##  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

```bash
# 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

```bash
# 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:

```bash
# 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`):

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

```python
# 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:

```python
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…