ubuntu_mcp_服务器

Name: ubuntu_mcp_服务器
Author: pazuzu1w

作者：pazuzu1w17 星标更新：2025-06-29

安装使用来源：spider==github.com

项目介绍

安全的Ubuntu MCP服务器

🔒 安全优先模型上下文协议服务器，用于安全的Ubuntu系统操作

一个经过强化、生产就绪的模型上下文协议（MCP）服务器，提供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

🔧 集成

Claude Desktop

在Linux上获取Claude Desktop

官方支持：Claude Desktop没有正式支持Linux，但社区已经创建了解决方案！

推荐方法：使用@aaddrick的社区Debian包：

# 下载并安装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  # 解决任何依赖问题

对于其他方法和故障排除，请参阅：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文件，15秒超时，256KB输出
sudo：禁用
shell执行：禁用（使用安全直接执行）

开发策略

开发环境更宽松：

额外允许路径：/opt，/usr/local
较少限制：访问更多系统区域
更大限制：10MB文件，60秒超时，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
指向敏感文件的符号链接

防止命令注入：

# 这些都被阻止：
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服务器持续运行并通过stdio通信
服务器正在等待MCP协议消息

“ModuleNotFoundError: 没有名为'mcp'的模块”

确保您使用的是虚拟环境Python解释器
检查您的Claude Desktop配置是否使用了.venv/bin/python3的完整路径

“SecurityViolation”错误

检查路径/命令是否被您的安全策略允许
查看审计日志/tmp/ubuntu_mcp_audit.log
考虑使用开发策略进行测试

“权限被拒绝”错误

验证您的用户是否有访问请求路径的权限
使用ls -la检查文件/目录权限

调试模式

# 启用详细日志
python main.py --log-level DEBUG --policy secure

# 查看审计日志
tail -f /tmp/ubuntu_mcp_audit.log

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南以获取详细信息。

开发设置

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
进行更改并编写测试
确保所有测试通过：python main.py --test && python main.py --security-test
提交拉取请求

代码标准

遵循PEP 8样式指南
为所有公共函数添加类型提示
包括全面的文档字符串
为新功能编写测试
维持安全优先的原则

📄 许可

本项目采用MIT许可 - 详见LICENSE文件。

🔐 安全披露

如果您发现安全漏洞，请发送电子邮件至[radjackbartok@proton.me]，而不是公开报告。我们非常重视安全问题并将迅速响应。

🙏 致谢

模型上下文协议团队提供的优秀协议
安全研究人员和信息安全社区的最佳实践
Python安全社区的持续指导

📈 发展路线图

增强的日志 - 带有更多上下文的结构化JSON日志
容器支持 - Docker集成和容器感知策略
网络工具 - 安全网络工具（ping、traceroute等）
进程管理 - 安全进程监控和控制
配置UI - 政策管理的Web界面
集成测试 - 全面的端到端测试
性能优化 - 缓存和性能改进
多用户支持 - 基于角色的访问控制

为注重安全的AI社区打造

💡 小贴士：从安全策略开始，并根据需要逐步增加权限。增加权限比从安全事件中恢复更容易！