MCP 7-Zip Server

⚠️ 注意：本项目为个人练手项目，目前暂时无法使用，仅供学习参考。

一个基于 Model Context Protocol (MCP) 的 7-Zip 压缩文件操作服务器，采用双引擎架构设计。本项目为个人学习 MCP 协议开发的练手作品，尚未完成全部功能验证，暂时无法正常使用。

✨ 核心特性

• 🔄 双引擎架构：同时支持内置打包引擎和系统本地引擎
• 🛡️ 安全沙盒：解压操作限制在安全目录，防止路径遍历攻击
• 📦 多格式支持：7z, zip, rar, tar, gz, bz2, xz 等主流格式
• 🔐 密码支持：支持加密压缩和解压
• ⚡ 智能探测：自动检测并选择可用的 7-Zip 引擎

🚀 快速开始

模式 A：开箱即用版（推荐小白）

由于使用了 optionalDependencies，默认 npx 会自动下载并使用内置的 7-Zip 引擎，无需额外配置。

Claude Desktop 配置 (~/Library/Application Support/Claude/claude_desktop_config.json 或 %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "7zip": {
      "command": "npx",
      "args": ["-y", "mcp-7zip-server"]
    }
  }
}

Cursor 配置 (.cursor/mcp.json):

{
  "mcpServers": {
    "7zip": {
      "command": "npx",
      "args": ["-y", "mcp-7zip-server"]
    }
  }
}

模式 B：轻量化极速版（推荐极客）

如果你已经安装了系统 7-Zip，可以跳过下载内置引擎，使用更轻量的安装方式：

npm install -g mcp-7zip-server --no-optional

Claude Desktop 配置:

{
  "mcpServers": {
    "7zip": {
      "command": "mcp-7zip-server",
      "env": {
        "USE_SYSTEM_7ZIP": "true"
      }
    }
  }
}

Cursor 配置:

{
  "mcpServers": {
    "7zip": {
      "command": "mcp-7zip-server",
      "env": {
        "USE_SYSTEM_7ZIP": "true"
      }
    }
  }
}

📋 环境变量

环境变量	说明	默认值	示例
SEVEN_ZIP_PATH	手动指定 7-Zip 可执行文件的绝对路径	-	/usr/local/bin/7z 或 C:\Program Files\7-Zip\7z.exe
USE_SYSTEM_7ZIP	强制使用系统安装的 7-Zip	false	true 或 1
MCP_7ZIP_SANDBOX	自定义沙盒目录路径	~/.mcp-7zip-sandbox	/path/to/sandbox

引擎优先级

服务器按以下优先级选择 7-Zip 引擎：

1. 最高优先级：SEVEN_ZIP_PATH 环境变量指定的路径
2. 次高优先级：USE_SYSTEM_7ZIP=true 强制使用系统 7-Zip
3. 默认行为：尝试内置引擎 → 降级到系统 7-Zip

🔧 MCP Tools

list_archive

列出压缩文件中的内容。

参数：

• archivePath (必填)：压缩文件的绝对路径
• password (可选)：解压密码

示例：

{
  "archivePath": "/path/to/archive.7z"
}

extract_archive

解压文件到沙盒目录。

参数：

• archivePath (必填)：压缩文件的绝对路径
• targetDir (可选)：解压目标目录（相对于沙盒目录）
• password (可选)：解压密码
• overwrite (可选)：覆盖策略 - overwrite（默认）、skip、rename

示例：

{
  "archivePath": "/path/to/archive.zip",
  "targetDir": "my-extracted-files",
  "overwrite": "skip"
}

create_archive

创建压缩文件。

参数：

• archivePath (必填)：输出压缩文件的路径
• files (必填)：要压缩的文件/目录路径列表
• format (可选)：压缩格式 - 7z（默认）、zip、tar、gz、bz2、xz
• password (可选)：加密密码
• compressionLevel (可选)：压缩级别 0-9（默认 5）

示例：

{
  "archivePath": "/path/to/output.7z",
  "files": ["/path/to/file1.txt", "/path/to/folder"],
  "format": "7z",
  "compressionLevel": 9
}

🛡️ 安全特性

防命令注入

• 使用 execFile 而非 exec，参数以数组形式传递
• 不使用 shell 执行，防止命令注入攻击

防路径遍历（沙盒机制）

• 解压操作强制限制在沙盒目录（默认 ~/.mcp-7zip-sandbox）
• 压缩时校验输入路径，禁止读取 /etc、~/.ssh 等敏感目录
• 可通过 MCP_7ZIP_SANDBOX 环境变量自定义沙盒位置

防上下文爆炸

• list_archive 输出超过 4000 字符自动截断
• 截断时显示文件总数统计，提示使用过滤条件

📦 支持的格式

格式	读取	写入	说明
7z	✅	✅	高压缩比，推荐
zip	✅	✅	通用兼容
rar	✅	❌	只读支持
tar	✅	✅	Unix 归档
gz	✅	✅	gzip 压缩
bz2	✅	✅	bzip2 压缩
xz	✅	✅	xz 压缩

🔍 故障排除

"未找到 7-Zip 引擎" 错误

解决方案（任选其一）：

1. 安装系统 7-Zip

   • Windows: https://www.7-zip.org/download.html
   • macOS: brew install p7zip
   • Linux: sudo apt install p7zip-full 或 sudo yum install p7zip

2. 重新安装内置引擎

   npm install -g mcp-7zip-server
   

3. 手动指定路径

   {
     "env": {
       "SEVEN_ZIP_PATH": "/path/to/7z"
     }
   }
   

权限问题

如果遇到权限错误，确保沙盒目录有写入权限：

mkdir -p ~/.mcp-7zip-sandbox
chmod 755 ~/.mcp-7zip-sandbox

🏗️ 开发

# 克隆仓库
git clone https://github.com/your-username/mcp-7zip-server.git
cd mcp-7zip-server

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 运行
npm start

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🙏 致谢

• 7-Zip - 强大的开源压缩软件
• 7zip-bin - 7-Zip 预编译二进制文件
• Model Context Protocol - MCP 协议规范