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社区打造

💡 使用建议：从安全策略开始，根据需要逐步增加权限。添加权限比从安全事件中恢复要容易得多！