Ubuntu MCP Server

🚀 安全的Ubuntu MCP服務器

🔒 這是一款以安全為首要考量的模型上下文協議（MCP）服務器，專為保障Ubuntu系統的安全操作而設計。它為AI助手提供對Ubuntu系統操作的安全、可控訪問，具備全面的安全控制、審計日誌記錄和縱深防禦原則。

✨ 主要特性

🛡️ 安全優先架構

• 路徑遍歷保護：通過允許列表/拒絕列表控制進行符號鏈接解析。
• 命令清理：通過安全的參數解析防止shell注入。
• 資源限制：對文件大小、執行超時時間和輸出大小進行控制。
• 全面的審計日誌記錄：記錄所有操作並關聯用戶信息。
• 縱深防禦：具備多個安全層，並採用故障安全默認設置。

🎯 核心功能

• 文件操作：在驗證權限的前提下，進行文件的讀取、寫入和目錄列表操作。
• 命令執行：通過白名單/黑名單過濾，安全地執行shell命令。
• 系統信息：監控操作系統細節、內存和磁盤使用情況。
• 軟件包管理：搜索和列出APT軟件包（安裝需要明確配置）。

🏗️ 生產就緒

• 模塊化設計：各功能模塊職責明確。
• 全面的錯誤處理：提供有意義的錯誤信息。
• 廣泛的測試套件：包括安全驗證測試。
• 可配置策略：適用於不同的用例和環境。
• 零依賴安全機制：核心安全功能不依賴外部軟件包。

🚀 快速開始

前提條件

• Ubuntu 18.04及以上版本（已在20.04、22.04、24.04版本上測試）。
• Python 3.9或更高版本。
• 標準Unix實用工具（如ls、cat、echo等）。

安裝

# 克隆倉庫
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp

# 創建並激活虛擬環境
python3 -m venv .venv
source .venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

# 使用內置測試驗證安裝
python main.py --test

基本用法

# 使用安全策略啟動（推薦）
python main.py --policy secure

# 使用開發策略啟動（更寬鬆）
python main.py --policy dev

# 測試安全措施
python main.py --security-test

💻 使用示例

基礎用法

# 使用安全策略啟動服務器
python main.py --policy secure

高級用法

# 在調試模式下啟動服務器，並使用安全策略
python main.py --log-level DEBUG --policy secure

📚 詳細文檔

🔧 集成

Claude Desktop

在Linux上獲取Claude Desktop

官方支持情況：Claude Desktop官方不支持Linux，但社區已經提供瞭解決方案！ 推薦方法：使用@aaddrick提供的社區Debian軟件包：

# 下載並安裝適用於Linux的Claude Desktop
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  # 修復任何依賴問題

如需瞭解其他方法和故障排除信息，請參閱：https://github.com/aaddrick/claude-desktop-debian

配置

Claude Desktop安裝完成後，將以下內容添加到配置文件（~/.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"
      }
    }
  }
}

⚠️ 重要提示：請使用絕對路徑和虛擬環境的Python解釋器。

驗證：重啟Claude Desktop後，你應該會看到“secure-ubuntu”作為已連接的服務器列出，並且Claude將可以訪問系統控制工具。

其他MCP客戶端

該服務器實現了標準的MCP協議，可與任何兼容MCP的客戶端配合使用：

# 使用mcp Python客戶端的示例
import asyncio
from mcp.client import ClientSession

async def example():
    # 連接到服務器
    # 具體實現取決於你的MCP客戶端
    pass

🛡️ 安全策略

安全策略（默認）

推薦用於生產環境和不可信環境：

• 允許路徑：~/, /tmp, /var/tmp
• 禁止路徑：/etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
• 命令白名單：ls, cat, echo, pwd, whoami, date, find, grep, apt（僅搜索）
• 資源限制：1MB文件，15s超時時間，256KB輸出
• sudo權限：禁用
• shell執行：禁用（使用安全的直接執行方式）

開發策略

適用於開發環境，限制更寬鬆：

• 額外允許路徑：/opt, /usr/local
• 更少限制：可訪問更多系統區域
• 更大限制：10MB文件，60s超時時間，1MB輸出
• 更多命令：允許使用大多數開發工具
• sudo權限：默認仍禁用（可啟用）

自定義策略

創建自己的安全策略：

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,  # 謹慎使用
    audit_actions=True
)

🔍 可用工具

文件操作

• list_directory(path)：列出目錄內容幷包含元數據。
• read_file(file_path)：讀取文件內容並進行大小驗證。
• write_file(file_path, content, create_dirs=False)：使用原子操作進行文件寫入。

系統操作

• execute_command(command, working_dir=None)：安全地執行shell命令。
• get_system_info()：獲取操作系統、內存和磁盤信息。

軟件包管理

• search_packages(query)：搜索APT軟件包倉庫。
• install_package(package_name)：檢查軟件包可用性（僅列出）。

🔒 安全特性

防範常見攻擊

路徑遍歷防範：

# 以下路徑均會被阻止：
../../../etc/passwd
/etc/passwd
/tmp/../etc/passwd
symlinks_to_sensitive_files

命令注入防範：

# 以下命令均會被阻止：
echo hello; rm -rf /
echo `cat /etc/passwd`
echo $(whoami)
ls | rm -rf /

資源耗盡防範：

• 文件大小限制防止內存耗盡。
• 執行超時時間防止進程掛起。
• 輸出大小限制防止日誌氾濫。
• 目錄列表限制防止枚舉攻擊。

審計跟蹤

所有操作都會記錄以下信息：

• 用戶信息
• 時間戳和操作類型
• 完整路徑解析
• 成功/失敗狀態
• 安全違規詳情

🧪 測試

功能測試

# 測試核心功能
python main.py --test

安全驗證

# 運行全面的安全測試
python main.py --security-test

手動測試

# 直接測試MCP協議
python test_client.py --simple

📊 示例用法

與AI助手集成後：

• 系統監控：

"檢查我的系統狀態和磁盤空間"

• 文件管理：

"列出我主目錄中的文件，並顯示最大的文件"

• 開發任務：

"檢查是否安裝了Python，並顯示版本信息"

• 日誌分析：

"查找我項目目錄中的所有錯誤文件"

⚙️ 配置

環境變量

• MCP_LOG_LEVEL：日誌級別（DEBUG, INFO, WARNING, ERROR）
• MCP_POLICY：安全策略（secure, dev）
• MCP_CONFIG_PATH：自定義配置文件的路徑

配置文件

創建config.json進行自定義設置：

{
  "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:
    """AI助手使用的工具描述"""
    try:
        # 使用控制器方法進行安全操作
        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:
    """創建自定義安全策略"""
    return SecurityPolicy(
        allowed_paths=["/your/paths"],
        forbidden_commands=["dangerous", "commands"],
        # ... 其他設置
    )

🔧 故障排除

常見問題

“服務器似乎掛起”

• 這是正常現象！MCP服務器會持續運行，並通過標準輸入輸出進行通信。
• 服務器正在等待MCP協議消息。

“ModuleNotFoundError: No module named 'mcp'”

• 確保你使用的是虛擬環境的Python解釋器。
• 檢查Claude Desktop配置是否使用了.venv/bin/python3的完整路徑。

“SecurityViolation”錯誤

• 檢查路徑/命令是否被你的安全策略允許。
• 查看/tmp/ubuntu_mcp_audit.log中的審計日誌。
• 考慮使用開發策略進行測試。

“Permission denied”錯誤

• 驗證你的用戶是否有權限訪問請求的路徑。
• 使用ls -la檢查文件/目錄權限。

調試模式

# 啟用詳細日誌記錄
python main.py --log-level DEBUG --policy secure

# 查看審計日誌
tail -f /tmp/ubuntu_mcp_audit.log

🤝 貢獻

我們歡迎貢獻！請參閱我們的貢獻指南以獲取詳細信息。

開發設置

1. 分叉倉庫。
2. 創建功能分支：git checkout -b feature/amazing-feature。
3. 進行更改並編寫測試。
4. 確保所有測試通過：python main.py --test && python main.py --security-test。
5. 提交拉取請求。

代碼標準

• 遵循PEP 8風格指南。
• 為所有公共函數添加類型提示。
• 包含全面的文檔字符串。
• 為新功能編寫測試。
• 堅持安全優先原則。

📄 許可證

本項目採用MIT許可證 - 詳情請參閱LICENSE文件。

🔐 安全披露

如果您發現安全漏洞，請發送電子郵件至 [radjackbartok@proton.me]，而不是創建公開問題。我們非常重視安全問題，並將及時響應。

🙏 致謝

• 模型上下文協議團隊提供了優秀的協議。
• 安全研究人員和信息安全社區分享了最佳實踐。
• Python安全社區提供了持續的指導。

📈 路線圖

• [ ] 增強日誌記錄：提供結構化的JSON日誌，幷包含更多上下文信息。
• [ ] 容器支持：集成Docker，並支持容器感知策略。
• [ ] 網絡工具：提供安全的網絡實用工具（如ping、traceroute等）。
• [ ] 進程管理：安全地監控和控制進程。
• [ ] 配置用戶界面：提供用於策略管理的Web界面。
• [ ] 集成測試：進行全面的端到端測試。
• [ ] 性能優化：通過緩存和其他方式提高性能。
• [ ] 多用戶支持：實現基於角色的訪問控制。

---

為注重安全的AI社區打造

💡 使用建議：從安全策略開始，根據需要逐步增加權限。添加權限比從安全事件中恢復要容易得多！